@frontmcp/adapters 0.6.0 → 0.6.2

package/src/openapi/openapi.frontmcp-schema.js

@@ -1,358 +0,0 @@
-"use strict";
-/**
- * Zod schemas for x-frontmcp OpenAPI extension validation.
- *
- * The x-frontmcp extension allows embedding FrontMCP-specific configuration
- * directly in OpenAPI specs. This module provides versioned schema validation
- * to ensure only valid data is used and invalid fields are warned about.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.FrontMcpExampleSchema = exports.FrontMcpCodeCallSchema = exports.FrontMcpCacheSchema = exports.FrontMcpAnnotationsSchema = exports.SUPPORTED_VERSIONS = exports.FRONTMCP_SCHEMA_VERSION = void 0;
-exports.validateFrontMcpExtension = validateFrontMcpExtension;
-const zod_1 = require("zod");
-/**
- * Current schema version for x-frontmcp extension.
- * Increment when making breaking changes to the schema.
- */
-exports.FRONTMCP_SCHEMA_VERSION = '1.0';
-/**
- * Supported schema versions.
- */
-exports.SUPPORTED_VERSIONS = ['1.0'];
-// ============================================================================
-// Annotations Schema (v1.0)
-// ============================================================================
-/**
- * Tool annotations schema - hints about tool behavior for AI clients.
- */
-exports.FrontMcpAnnotationsSchema = zod_1.z.object({
-    /** Human-readable title for the tool */
-    title: zod_1.z.string().optional(),
-    /** If true, the tool does not modify its environment */
-    readOnlyHint: zod_1.z.boolean().optional(),
-    /** If true, the tool may perform destructive updates */
-    destructiveHint: zod_1.z.boolean().optional(),
-    /** If true, calling repeatedly with same args has no additional effect */
-    idempotentHint: zod_1.z.boolean().optional(),
-    /** If true, tool may interact with external entities */
-    openWorldHint: zod_1.z.boolean().optional(),
-});
-// ============================================================================
-// Cache Schema (v1.0)
-// ============================================================================
-/**
- * Cache configuration schema.
- */
-exports.FrontMcpCacheSchema = zod_1.z.object({
-    /** Time-to-live in seconds for cached responses */
-    ttl: zod_1.z.number().int().positive().optional(),
-    /** If true, cache window slides on each access */
-    slideWindow: zod_1.z.boolean().optional(),
-});
-// ============================================================================
-// CodeCall Schema (v1.0)
-// ============================================================================
-/**
- * CodeCall plugin configuration schema.
- */
-exports.FrontMcpCodeCallSchema = zod_1.z.object({
-    /** Whether this tool can be used via CodeCall */
-    enabledInCodeCall: zod_1.z.boolean().optional(),
-    /** If true, stays visible in list_tools when CodeCall is active */
-    visibleInListTools: zod_1.z.boolean().optional(),
-});
-// ============================================================================
-// Example Schema (v1.0)
-// ============================================================================
-/**
- * Tool usage example schema.
- */
-exports.FrontMcpExampleSchema = zod_1.z.object({
-    /** Description of the example */
-    description: zod_1.z.string(),
-    /** Example input values */
-    input: zod_1.z.record(zod_1.z.string(), zod_1.z.any()),
-    /** Expected output (optional) */
-    output: zod_1.z.any().optional(),
-});
-// ============================================================================
-// Known Fields for Validation
-// ============================================================================
-/** Known field names for validation */
-const KNOWN_EXTENSION_FIELDS = new Set([
-    'version',
-    'annotations',
-    'cache',
-    'codecall',
-    'tags',
-    'hideFromDiscovery',
-    'examples',
-]);
-const KNOWN_ANNOTATION_FIELDS = new Set([
-    'title',
-    'readOnlyHint',
-    'destructiveHint',
-    'idempotentHint',
-    'openWorldHint',
-]);
-const KNOWN_CACHE_FIELDS = new Set(['ttl', 'slideWindow']);
-const KNOWN_CODECALL_FIELDS = new Set(['enabledInCodeCall', 'visibleInListTools']);
-// ============================================================================
-// Schema Validation Functions
-// ============================================================================
-/**
- * Validate and parse x-frontmcp extension data.
- *
- * This function:
- * 1. Detects the schema version (defaults to current)
- * 2. Validates each field against the appropriate schema
- * 3. Returns only valid fields, ignoring invalid ones
- * 4. Collects warnings for invalid/unknown fields
- *
- * @param rawData - Raw x-frontmcp data from OpenAPI spec
- * @param toolName - Tool name for error context
- * @param logger - Logger for warnings
- * @returns Validation result with valid data and warnings
- */
-function validateFrontMcpExtension(rawData, toolName, logger) {
-    const warnings = [];
-    // Handle null/undefined
-    if (rawData === null || rawData === undefined) {
-        return { success: true, data: null, warnings: [] };
-    }
-    // Must be an object
-    if (typeof rawData !== 'object' || Array.isArray(rawData)) {
-        warnings.push(`x-frontmcp must be an object, got ${Array.isArray(rawData) ? 'array' : typeof rawData}`);
-        logger.warn(`[${toolName}] Invalid x-frontmcp extension: ${warnings[0]}`);
-        return { success: false, data: null, warnings };
-    }
-    const data = rawData;
-    // Detect version
-    const version = typeof data['version'] === 'string' ? data['version'] : exports.FRONTMCP_SCHEMA_VERSION;
-    // Check if version is supported
-    if (!exports.SUPPORTED_VERSIONS.includes(version)) {
-        warnings.push(`Unsupported x-frontmcp version '${version}'. Supported versions: ${exports.SUPPORTED_VERSIONS.join(', ')}`);
-        logger.warn(`[${toolName}] ${warnings[0]}`);
-        return { success: false, data: null, warnings };
-    }
-    // Extract valid fields and collect warnings
-    const validData = extractValidFields(data, version, warnings);
-    if (warnings.length > 0) {
-        logger.warn(`[${toolName}] x-frontmcp extension has invalid fields that were ignored:`);
-        warnings.forEach((w) => logger.warn(`  - ${w}`));
-    }
-    return {
-        success: true,
-        data: validData,
-        warnings,
-    };
-}
-/**
- * Extract valid fields from x-frontmcp data, collecting warnings for invalid fields.
- */
-function extractValidFields(data, version, warnings) {
-    const result = {
-        version: version,
-    };
-    // Warn about unknown top-level fields
-    for (const key of Object.keys(data)) {
-        if (!KNOWN_EXTENSION_FIELDS.has(key)) {
-            warnings.push(`Unknown field '${key}' in x-frontmcp (will be ignored)`);
-        }
-    }
-    // Validate annotations
-    if (data['annotations'] !== undefined) {
-        const annotationsResult = exports.FrontMcpAnnotationsSchema.safeParse(data['annotations']);
-        if (annotationsResult.success) {
-            result.annotations = annotationsResult.data;
-        }
-        else {
-            const issues = formatZodIssues(annotationsResult.error.issues, 'annotations');
-            warnings.push(...issues);
-            // Try to extract valid annotation fields
-            result.annotations = extractValidAnnotations(data['annotations'], warnings);
-        }
-    }
-    // Validate cache
-    if (data['cache'] !== undefined) {
-        const cacheResult = exports.FrontMcpCacheSchema.safeParse(data['cache']);
-        if (cacheResult.success) {
-            result.cache = cacheResult.data;
-        }
-        else {
-            const issues = formatZodIssues(cacheResult.error.issues, 'cache');
-            warnings.push(...issues);
-            // Try to extract valid cache fields
-            result.cache = extractValidCache(data['cache'], warnings);
-        }
-    }
-    // Validate codecall
-    if (data['codecall'] !== undefined) {
-        const codecallResult = exports.FrontMcpCodeCallSchema.safeParse(data['codecall']);
-        if (codecallResult.success) {
-            result.codecall = codecallResult.data;
-        }
-        else {
-            const issues = formatZodIssues(codecallResult.error.issues, 'codecall');
-            warnings.push(...issues);
-            // Try to extract valid codecall fields
-            result.codecall = extractValidCodeCall(data['codecall'], warnings);
-        }
-    }
-    // Validate tags
-    if (data['tags'] !== undefined) {
-        const tagsSchema = zod_1.z.array(zod_1.z.string());
-        const tagsResult = tagsSchema.safeParse(data['tags']);
-        if (tagsResult.success) {
-            result.tags = tagsResult.data;
-        }
-        else {
-            warnings.push(`Invalid 'tags': expected array of strings`);
-            // Try to extract valid tags
-            result.tags = extractValidTags(data['tags']);
-        }
-    }
-    // Validate hideFromDiscovery
-    if (data['hideFromDiscovery'] !== undefined) {
-        if (typeof data['hideFromDiscovery'] === 'boolean') {
-            result.hideFromDiscovery = data['hideFromDiscovery'];
-        }
-        else {
-            warnings.push(`Invalid 'hideFromDiscovery': expected boolean, got ${typeof data['hideFromDiscovery']}`);
-        }
-    }
-    // Validate examples
-    if (data['examples'] !== undefined) {
-        const examplesSchema = zod_1.z.array(exports.FrontMcpExampleSchema);
-        const examplesResult = examplesSchema.safeParse(data['examples']);
-        if (examplesResult.success) {
-            result.examples = examplesResult.data;
-        }
-        else {
-            warnings.push(`Invalid 'examples': some examples have invalid format`);
-            // Try to extract valid examples
-            result.examples = extractValidExamples(data['examples'], warnings);
-        }
-    }
-    return result;
-}
-/**
- * Extract valid annotation fields.
- */
-function extractValidAnnotations(data, warnings) {
-    if (typeof data !== 'object' || data === null)
-        return undefined;
-    const obj = data;
-    const result = {};
-    for (const field of KNOWN_ANNOTATION_FIELDS) {
-        if (obj[field] !== undefined) {
-            if (field === 'title' && typeof obj[field] === 'string') {
-                result.title = obj[field];
-            }
-            else if (field !== 'title' && typeof obj[field] === 'boolean') {
-                result[field] = obj[field];
-            }
-        }
-    }
-    // Warn about unknown annotation fields
-    for (const key of Object.keys(obj)) {
-        if (!KNOWN_ANNOTATION_FIELDS.has(key)) {
-            warnings.push(`Unknown field 'annotations.${key}' (will be ignored)`);
-        }
-    }
-    return Object.keys(result).length > 0 ? result : undefined;
-}
-/**
- * Extract valid cache fields.
- */
-function extractValidCache(data, warnings) {
-    if (typeof data !== 'object' || data === null)
-        return undefined;
-    const obj = data;
-    const result = {};
-    if (typeof obj['ttl'] === 'number' && Number.isInteger(obj['ttl']) && obj['ttl'] > 0) {
-        result.ttl = obj['ttl'];
-    }
-    else if (obj['ttl'] !== undefined) {
-        warnings.push(`Invalid 'cache.ttl': expected positive integer`);
-    }
-    if (typeof obj['slideWindow'] === 'boolean') {
-        result.slideWindow = obj['slideWindow'];
-    }
-    else if (obj['slideWindow'] !== undefined) {
-        warnings.push(`Invalid 'cache.slideWindow': expected boolean`);
-    }
-    // Warn about unknown cache fields
-    for (const key of Object.keys(obj)) {
-        if (!KNOWN_CACHE_FIELDS.has(key)) {
-            warnings.push(`Unknown field 'cache.${key}' (will be ignored)`);
-        }
-    }
-    return Object.keys(result).length > 0 ? result : undefined;
-}
-/**
- * Extract valid codecall fields.
- */
-function extractValidCodeCall(data, warnings) {
-    if (typeof data !== 'object' || data === null)
-        return undefined;
-    const obj = data;
-    const result = {};
-    if (typeof obj['enabledInCodeCall'] === 'boolean') {
-        result.enabledInCodeCall = obj['enabledInCodeCall'];
-    }
-    else if (obj['enabledInCodeCall'] !== undefined) {
-        warnings.push(`Invalid 'codecall.enabledInCodeCall': expected boolean`);
-    }
-    if (typeof obj['visibleInListTools'] === 'boolean') {
-        result.visibleInListTools = obj['visibleInListTools'];
-    }
-    else if (obj['visibleInListTools'] !== undefined) {
-        warnings.push(`Invalid 'codecall.visibleInListTools': expected boolean`);
-    }
-    // Warn about unknown codecall fields
-    for (const key of Object.keys(obj)) {
-        if (!KNOWN_CODECALL_FIELDS.has(key)) {
-            warnings.push(`Unknown field 'codecall.${key}' (will be ignored)`);
-        }
-    }
-    return Object.keys(result).length > 0 ? result : undefined;
-}
-/**
- * Extract valid tags from array.
- */
-function extractValidTags(data) {
-    if (!Array.isArray(data))
-        return undefined;
-    const validTags = data.filter((item) => typeof item === 'string');
-    return validTags.length > 0 ? validTags : undefined;
-}
-/**
- * Extract valid examples from array.
- */
-function extractValidExamples(data, warnings) {
-    if (!Array.isArray(data))
-        return undefined;
-    const validExamples = [];
-    for (let i = 0; i < data.length; i++) {
-        const item = data[i];
-        const result = exports.FrontMcpExampleSchema.safeParse(item);
-        if (result.success) {
-            validExamples.push(result.data);
-        }
-        else {
-            warnings.push(`Invalid example at index ${i}: ${formatZodIssues(result.error.issues, `examples[${i}]`).join(', ')}`);
-        }
-    }
-    return validExamples.length > 0 ? validExamples : undefined;
-}
-/**
- * Format Zod validation issues into readable messages.
- */
-function formatZodIssues(issues, prefix) {
-    return issues.map((issue) => {
-        const path = issue.path.length > 0 ? `${prefix}.${issue.path.join('.')}` : prefix;
-        return `Invalid '${path}': ${issue.message}`;
-    });
-}
-//# sourceMappingURL=openapi.frontmcp-schema.js.map

package/src/openapi/openapi.frontmcp-schema.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"openapi.frontmcp-schema.js","sourceRoot":"","sources":["../../../src/openapi/openapi.frontmcp-schema.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Zod schemas for x-frontmcp OpenAPI extension validation.\n *\n * The x-frontmcp extension allows embedding FrontMCP-specific configuration\n * directly in OpenAPI specs. This module provides versioned schema validation\n * to ensure only valid data is used and invalid fields are warned about.\n */\n\nimport { z } from 'zod';\nimport type { FrontMcpLogger } from '@frontmcp/sdk';\n\n/**\n * Current schema version for x-frontmcp extension.\n * Increment when making breaking changes to the schema.\n */\nexport const FRONTMCP_SCHEMA_VERSION = '1.0' as const;\n\n/**\n * Supported schema versions.\n */\nexport const SUPPORTED_VERSIONS = ['1.0'] as const;\nexport type FrontMcpSchemaVersion = (typeof SUPPORTED_VERSIONS)[number];\n\n// ============================================================================\n// Annotations Schema (v1.0)\n// ============================================================================\n\n/**\n * Tool annotations schema - hints about tool behavior for AI clients.\n */\nexport const FrontMcpAnnotationsSchema = z.object({\n  /** Human-readable title for the tool */\n  title: z.string().optional(),\n  /** If true, the tool does not modify its environment */\n  readOnlyHint: z.boolean().optional(),\n  /** If true, the tool may perform destructive updates */\n  destructiveHint: z.boolean().optional(),\n  /** If true, calling repeatedly with same args has no additional effect */\n  idempotentHint: z.boolean().optional(),\n  /** If true, tool may interact with external entities */\n  openWorldHint: z.boolean().optional(),\n});\n\nexport type FrontMcpAnnotations = z.infer<typeof FrontMcpAnnotationsSchema>;\n\n// ============================================================================\n// Cache Schema (v1.0)\n// ============================================================================\n\n/**\n * Cache configuration schema.\n */\nexport const FrontMcpCacheSchema = z.object({\n  /** Time-to-live in seconds for cached responses */\n  ttl: z.number().int().positive().optional(),\n  /** If true, cache window slides on each access */\n  slideWindow: z.boolean().optional(),\n});\n\nexport type FrontMcpCache = z.infer<typeof FrontMcpCacheSchema>;\n\n// ============================================================================\n// CodeCall Schema (v1.0)\n// ============================================================================\n\n/**\n * CodeCall plugin configuration schema.\n */\nexport const FrontMcpCodeCallSchema = z.object({\n  /** Whether this tool can be used via CodeCall */\n  enabledInCodeCall: z.boolean().optional(),\n  /** If true, stays visible in list_tools when CodeCall is active */\n  visibleInListTools: z.boolean().optional(),\n});\n\nexport type FrontMcpCodeCall = z.infer<typeof FrontMcpCodeCallSchema>;\n\n// ============================================================================\n// Example Schema (v1.0)\n// ============================================================================\n\n/**\n * Tool usage example schema.\n */\nexport const FrontMcpExampleSchema = z.object({\n  /** Description of the example */\n  description: z.string(),\n  /** Example input values */\n  input: z.record(z.string(), z.any()),\n  /** Expected output (optional) */\n  output: z.any().optional(),\n});\n\nexport type FrontMcpExample = z.infer<typeof FrontMcpExampleSchema>;\n\n// ============================================================================\n// Known Fields for Validation\n// ============================================================================\n\n/** Known field names for validation */\nconst KNOWN_EXTENSION_FIELDS = new Set([\n  'version',\n  'annotations',\n  'cache',\n  'codecall',\n  'tags',\n  'hideFromDiscovery',\n  'examples',\n]);\n\nconst KNOWN_ANNOTATION_FIELDS = new Set([\n  'title',\n  'readOnlyHint',\n  'destructiveHint',\n  'idempotentHint',\n  'openWorldHint',\n]);\n\nconst KNOWN_CACHE_FIELDS = new Set(['ttl', 'slideWindow']);\nconst KNOWN_CODECALL_FIELDS = new Set(['enabledInCodeCall', 'visibleInListTools']);\n\n// ============================================================================\n// Validated Extension Type (after parsing)\n// ============================================================================\n\n/**\n * Validated x-frontmcp extension data.\n * This is the output after schema validation.\n */\nexport interface ValidatedFrontMcpExtension {\n  version: FrontMcpSchemaVersion;\n  annotations?: FrontMcpAnnotations;\n  cache?: FrontMcpCache;\n  codecall?: FrontMcpCodeCall;\n  tags?: string[];\n  hideFromDiscovery?: boolean;\n  examples?: FrontMcpExample[];\n}\n\n// ============================================================================\n// Validation Result\n// ============================================================================\n\nexport interface FrontMcpValidationResult {\n  /** Whether validation succeeded (may still have warnings) */\n  success: boolean;\n  /** Validated data (only valid fields) */\n  data: ValidatedFrontMcpExtension | null;\n  /** Validation warnings (invalid fields that were ignored) */\n  warnings: string[];\n}\n\n// ============================================================================\n// Schema Validation Functions\n// ============================================================================\n\n/**\n * Validate and parse x-frontmcp extension data.\n *\n * This function:\n * 1. Detects the schema version (defaults to current)\n * 2. Validates each field against the appropriate schema\n * 3. Returns only valid fields, ignoring invalid ones\n * 4. Collects warnings for invalid/unknown fields\n *\n * @param rawData - Raw x-frontmcp data from OpenAPI spec\n * @param toolName - Tool name for error context\n * @param logger - Logger for warnings\n * @returns Validation result with valid data and warnings\n */\nexport function validateFrontMcpExtension(\n  rawData: unknown,\n  toolName: string,\n  logger: FrontMcpLogger,\n): FrontMcpValidationResult {\n  const warnings: string[] = [];\n\n  // Handle null/undefined\n  if (rawData === null || rawData === undefined) {\n    return { success: true, data: null, warnings: [] };\n  }\n\n  // Must be an object\n  if (typeof rawData !== 'object' || Array.isArray(rawData)) {\n    warnings.push(`x-frontmcp must be an object, got ${Array.isArray(rawData) ? 'array' : typeof rawData}`);\n    logger.warn(`[${toolName}] Invalid x-frontmcp extension: ${warnings[0]}`);\n    return { success: false, data: null, warnings };\n  }\n\n  const data = rawData as Record<string, unknown>;\n\n  // Detect version\n  const version = typeof data['version'] === 'string' ? data['version'] : FRONTMCP_SCHEMA_VERSION;\n\n  // Check if version is supported\n  if (!SUPPORTED_VERSIONS.includes(version as FrontMcpSchemaVersion)) {\n    warnings.push(`Unsupported x-frontmcp version '${version}'. Supported versions: ${SUPPORTED_VERSIONS.join(', ')}`);\n    logger.warn(`[${toolName}] ${warnings[0]}`);\n    return { success: false, data: null, warnings };\n  }\n\n  // Extract valid fields and collect warnings\n  const validData = extractValidFields(data, version, warnings);\n\n  if (warnings.length > 0) {\n    logger.warn(`[${toolName}] x-frontmcp extension has invalid fields that were ignored:`);\n    warnings.forEach((w) => logger.warn(`  - ${w}`));\n  }\n\n  return {\n    success: true,\n    data: validData,\n    warnings,\n  };\n}\n\n/**\n * Extract valid fields from x-frontmcp data, collecting warnings for invalid fields.\n */\nfunction extractValidFields(\n  data: Record<string, unknown>,\n  version: string,\n  warnings: string[],\n): ValidatedFrontMcpExtension {\n  const result: ValidatedFrontMcpExtension = {\n    version: version as FrontMcpSchemaVersion,\n  };\n\n  // Warn about unknown top-level fields\n  for (const key of Object.keys(data)) {\n    if (!KNOWN_EXTENSION_FIELDS.has(key)) {\n      warnings.push(`Unknown field '${key}' in x-frontmcp (will be ignored)`);\n    }\n  }\n\n  // Validate annotations\n  if (data['annotations'] !== undefined) {\n    const annotationsResult = FrontMcpAnnotationsSchema.safeParse(data['annotations']);\n    if (annotationsResult.success) {\n      result.annotations = annotationsResult.data;\n    } else {\n      const issues = formatZodIssues(annotationsResult.error.issues, 'annotations');\n      warnings.push(...issues);\n      // Try to extract valid annotation fields\n      result.annotations = extractValidAnnotations(data['annotations'], warnings);\n    }\n  }\n\n  // Validate cache\n  if (data['cache'] !== undefined) {\n    const cacheResult = FrontMcpCacheSchema.safeParse(data['cache']);\n    if (cacheResult.success) {\n      result.cache = cacheResult.data;\n    } else {\n      const issues = formatZodIssues(cacheResult.error.issues, 'cache');\n      warnings.push(...issues);\n      // Try to extract valid cache fields\n      result.cache = extractValidCache(data['cache'], warnings);\n    }\n  }\n\n  // Validate codecall\n  if (data['codecall'] !== undefined) {\n    const codecallResult = FrontMcpCodeCallSchema.safeParse(data['codecall']);\n    if (codecallResult.success) {\n      result.codecall = codecallResult.data;\n    } else {\n      const issues = formatZodIssues(codecallResult.error.issues, 'codecall');\n      warnings.push(...issues);\n      // Try to extract valid codecall fields\n      result.codecall = extractValidCodeCall(data['codecall'], warnings);\n    }\n  }\n\n  // Validate tags\n  if (data['tags'] !== undefined) {\n    const tagsSchema = z.array(z.string());\n    const tagsResult = tagsSchema.safeParse(data['tags']);\n    if (tagsResult.success) {\n      result.tags = tagsResult.data;\n    } else {\n      warnings.push(`Invalid 'tags': expected array of strings`);\n      // Try to extract valid tags\n      result.tags = extractValidTags(data['tags']);\n    }\n  }\n\n  // Validate hideFromDiscovery\n  if (data['hideFromDiscovery'] !== undefined) {\n    if (typeof data['hideFromDiscovery'] === 'boolean') {\n      result.hideFromDiscovery = data['hideFromDiscovery'];\n    } else {\n      warnings.push(`Invalid 'hideFromDiscovery': expected boolean, got ${typeof data['hideFromDiscovery']}`);\n    }\n  }\n\n  // Validate examples\n  if (data['examples'] !== undefined) {\n    const examplesSchema = z.array(FrontMcpExampleSchema);\n    const examplesResult = examplesSchema.safeParse(data['examples']);\n    if (examplesResult.success) {\n      result.examples = examplesResult.data;\n    } else {\n      warnings.push(`Invalid 'examples': some examples have invalid format`);\n      // Try to extract valid examples\n      result.examples = extractValidExamples(data['examples'], warnings);\n    }\n  }\n\n  return result;\n}\n\n/**\n * Extract valid annotation fields.\n */\nfunction extractValidAnnotations(data: unknown, warnings: string[]): FrontMcpAnnotations | undefined {\n  if (typeof data !== 'object' || data === null) return undefined;\n\n  const obj = data as Record<string, unknown>;\n  const result: FrontMcpAnnotations = {};\n\n  for (const field of KNOWN_ANNOTATION_FIELDS) {\n    if (obj[field] !== undefined) {\n      if (field === 'title' && typeof obj[field] === 'string') {\n        result.title = obj[field] as string;\n      } else if (field !== 'title' && typeof obj[field] === 'boolean') {\n        (result as Record<string, unknown>)[field] = obj[field];\n      }\n    }\n  }\n\n  // Warn about unknown annotation fields\n  for (const key of Object.keys(obj)) {\n    if (!KNOWN_ANNOTATION_FIELDS.has(key)) {\n      warnings.push(`Unknown field 'annotations.${key}' (will be ignored)`);\n    }\n  }\n\n  return Object.keys(result).length > 0 ? result : undefined;\n}\n\n/**\n * Extract valid cache fields.\n */\nfunction extractValidCache(data: unknown, warnings: string[]): FrontMcpCache | undefined {\n  if (typeof data !== 'object' || data === null) return undefined;\n\n  const obj = data as Record<string, unknown>;\n  const result: FrontMcpCache = {};\n\n  if (typeof obj['ttl'] === 'number' && Number.isInteger(obj['ttl']) && obj['ttl'] > 0) {\n    result.ttl = obj['ttl'];\n  } else if (obj['ttl'] !== undefined) {\n    warnings.push(`Invalid 'cache.ttl': expected positive integer`);\n  }\n\n  if (typeof obj['slideWindow'] === 'boolean') {\n    result.slideWindow = obj['slideWindow'];\n  } else if (obj['slideWindow'] !== undefined) {\n    warnings.push(`Invalid 'cache.slideWindow': expected boolean`);\n  }\n\n  // Warn about unknown cache fields\n  for (const key of Object.keys(obj)) {\n    if (!KNOWN_CACHE_FIELDS.has(key)) {\n      warnings.push(`Unknown field 'cache.${key}' (will be ignored)`);\n    }\n  }\n\n  return Object.keys(result).length > 0 ? result : undefined;\n}\n\n/**\n * Extract valid codecall fields.\n */\nfunction extractValidCodeCall(data: unknown, warnings: string[]): FrontMcpCodeCall | undefined {\n  if (typeof data !== 'object' || data === null) return undefined;\n\n  const obj = data as Record<string, unknown>;\n  const result: FrontMcpCodeCall = {};\n\n  if (typeof obj['enabledInCodeCall'] === 'boolean') {\n    result.enabledInCodeCall = obj['enabledInCodeCall'];\n  } else if (obj['enabledInCodeCall'] !== undefined) {\n    warnings.push(`Invalid 'codecall.enabledInCodeCall': expected boolean`);\n  }\n\n  if (typeof obj['visibleInListTools'] === 'boolean') {\n    result.visibleInListTools = obj['visibleInListTools'];\n  } else if (obj['visibleInListTools'] !== undefined) {\n    warnings.push(`Invalid 'codecall.visibleInListTools': expected boolean`);\n  }\n\n  // Warn about unknown codecall fields\n  for (const key of Object.keys(obj)) {\n    if (!KNOWN_CODECALL_FIELDS.has(key)) {\n      warnings.push(`Unknown field 'codecall.${key}' (will be ignored)`);\n    }\n  }\n\n  return Object.keys(result).length > 0 ? result : undefined;\n}\n\n/**\n * Extract valid tags from array.\n */\nfunction extractValidTags(data: unknown): string[] | undefined {\n  if (!Array.isArray(data)) return undefined;\n\n  const validTags = data.filter((item): item is string => typeof item === 'string');\n  return validTags.length > 0 ? validTags : undefined;\n}\n\n/**\n * Extract valid examples from array.\n */\nfunction extractValidExamples(data: unknown, warnings: string[]): FrontMcpExample[] | undefined {\n  if (!Array.isArray(data)) return undefined;\n\n  const validExamples: FrontMcpExample[] = [];\n\n  for (let i = 0; i < data.length; i++) {\n    const item = data[i];\n    const result = FrontMcpExampleSchema.safeParse(item);\n    if (result.success) {\n      validExamples.push(result.data);\n    } else {\n      warnings.push(\n        `Invalid example at index ${i}: ${formatZodIssues(result.error.issues, `examples[${i}]`).join(', ')}`,\n      );\n    }\n  }\n\n  return validExamples.length > 0 ? validExamples : undefined;\n}\n\n/** Zod issue shape for formatting */\ninterface ZodIssue {\n  path: PropertyKey[];\n  message: string;\n}\n\n/**\n * Format Zod validation issues into readable messages.\n */\nfunction formatZodIssues(issues: ZodIssue[], prefix: string): string[] {\n  return issues.map((issue) => {\n    const path = issue.path.length > 0 ? `${prefix}.${issue.path.join('.')}` : prefix;\n    return `Invalid '${path}': ${issue.message}`;\n  });\n}\n"]}

package/src/openapi/openapi.security.js

@@ -1,242 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createSecurityContextFromAuth = createSecurityContextFromAuth;
-exports.extractSecuritySchemes = extractSecuritySchemes;
-exports.validateSecurityConfiguration = validateSecurityConfiguration;
-exports.resolveToolSecurity = resolveToolSecurity;
-const mcp_from_openapi_1 = require("mcp-from-openapi");
-/**
- * Resolve security context from FrontMCP context with support for multiple auth providers
- *
- * @param tool - OpenAPI tool to resolve security for
- * @param ctx - FrontMCP request context with authInfo, sessionId, traceId, etc.
- * @param options - Adapter options with auth configuration
- * @returns Security context for resolver
- */
-async function createSecurityContextFromAuth(tool, ctx, options) {
-    // 1. Use custom security resolver if provided (highest priority)
-    if (options.securityResolver) {
-        return await options.securityResolver(tool, ctx);
-    }
-    // 2. Use auth provider mapper if provided
-    if (options.authProviderMapper) {
-        const context = (0, mcp_from_openapi_1.createSecurityContext)({});
-        // Find all security schemes used by this tool
-        const securitySchemes = new Set();
-        for (const mapper of tool.mapper) {
-            if (mapper.security?.scheme) {
-                securitySchemes.add(mapper.security.scheme);
-            }
-        }
-        // Map each security scheme to its auth provider
-        // Process all schemes - first matching token for each auth type (jwt, apiKey, basic, oauth2Token)
-        for (const scheme of securitySchemes) {
-            const authExtractor = options.authProviderMapper[scheme];
-            if (authExtractor) {
-                try {
-                    const token = authExtractor(ctx);
-                    // Validate return type - must be string or undefined/null
-                    if (token !== undefined && token !== null && typeof token !== 'string') {
-                        throw new Error(`authProviderMapper['${scheme}'] must return a string or undefined, ` + `but returned: ${typeof token}`);
-                    }
-                    // Reject empty string tokens explicitly - indicates misconfiguration
-                    if (token === '') {
-                        throw new Error(`authProviderMapper['${scheme}'] returned empty string. ` +
-                            `Return undefined/null if no token is available, or provide a valid token.`);
-                    }
-                    if (token) {
-                        // Route token to correct context field based on scheme type
-                        // Look up the scheme info from the mapper to determine type
-                        const schemeMapper = tool.mapper.find((m) => m.security?.scheme === scheme);
-                        const schemeType = schemeMapper?.security?.type?.toLowerCase();
-                        const httpScheme = schemeMapper?.security?.httpScheme?.toLowerCase();
-                        // Route based on security scheme type (first token for each type wins)
-                        if (schemeType === 'apikey') {
-                            if (!context.apiKey) {
-                                context.apiKey = token;
-                            }
-                        }
-                        else if (schemeType === 'http' && httpScheme === 'basic') {
-                            if (!context.basic) {
-                                context.basic = token;
-                            }
-                        }
-                        else if (schemeType === 'oauth2') {
-                            if (!context.oauth2Token) {
-                                context.oauth2Token = token;
-                            }
-                        }
-                        else {
-                            // Default to jwt for http bearer and unknown types
-                            if (!context.jwt) {
-                                context.jwt = token;
-                            }
-                        }
-                        // Continue checking other schemes - don't break
-                        // This allows validation to see all configured providers
-                    }
-                }
-                catch (err) {
-                    // Re-throw validation errors as-is
-                    if (err instanceof Error && err.message.includes('authProviderMapper')) {
-                        throw err;
-                    }
-                    // Wrap other errors with context
-                    const errorMessage = err instanceof Error ? err.message : String(err);
-                    throw new Error(`authProviderMapper['${scheme}'] threw an error: ${errorMessage}`);
-                }
-            }
-        }
-        // If no auth was set from providers, fall back to ctx.authInfo.token
-        // Only fall back if ALL auth fields are empty (not just jwt)
-        const hasAnyAuth = context.jwt || context.apiKey || context.basic || context.oauth2Token;
-        const authToken = ctx.authInfo?.token;
-        if (!hasAnyAuth && authToken) {
-            // Validate type before assignment to prevent non-string values
-            if (typeof authToken !== 'string') {
-                throw new Error(`authInfo.token must be a string, but got: ${typeof authToken}`);
-            }
-            context.jwt = authToken;
-        }
-        return context;
-    }
-    // 3. Use static auth if provided
-    if (options.staticAuth) {
-        return (0, mcp_from_openapi_1.createSecurityContext)(options.staticAuth);
-    }
-    // 4. Default: use main JWT token from auth context
-    return (0, mcp_from_openapi_1.createSecurityContext)({
-        jwt: ctx.authInfo?.token,
-    });
-}
-/**
- * Extract all security schemes used by a set of tools
- *
- * @param tools - OpenAPI tools
- * @returns Set of security scheme names
- */
-function extractSecuritySchemes(tools) {
-    const schemes = new Set();
-    for (const tool of tools) {
-        for (const mapper of tool.mapper) {
-            if (mapper.security?.scheme) {
-                schemes.add(mapper.security.scheme);
-            }
-        }
-    }
-    return schemes;
-}
-/**
- * Validate security configuration against OpenAPI security requirements
- *
- * @param tools - OpenAPI tools
- * @param options - Adapter options
- * @returns Validation result with errors and warnings
- */
-function validateSecurityConfiguration(tools, options) {
-    const result = {
-        valid: true,
-        missingMappings: [],
-        warnings: [],
-        securityRiskScore: 'low',
-    };
-    // Extract all security schemes used
-    const securitySchemes = extractSecuritySchemes(tools);
-    // If includeSecurityInInput is true, auth is provided by user (high security risk)
-    const includeSecurityInInput = options.generateOptions?.includeSecurityInInput ?? false;
-    if (includeSecurityInInput) {
-        result.securityRiskScore = 'high';
-        result.warnings.push('SECURITY WARNING: includeSecurityInInput is enabled. Users will provide authentication directly in tool inputs. This increases security risk as credentials may be logged or exposed.');
-        // Don't validate mappings if security is in input
-        return result;
-    }
-    // Check if we have custom security resolver (most flexible, low risk)
-    if (options.securityResolver) {
-        result.securityRiskScore = 'low';
-        result.warnings.push('INFO: Using custom securityResolver. Ensure your resolver properly validates and secures credentials from context.');
-        return result;
-    }
-    // Check if we have static auth (medium risk - static credentials)
-    if (options.staticAuth && Object.keys(options.staticAuth).length > 0) {
-        result.securityRiskScore = 'medium';
-        result.warnings.push('SECURITY INFO: Using staticAuth with hardcoded credentials. Ensure credentials are stored securely (environment variables, secrets manager).');
-        // If static auth is provided, assume it covers all schemes
-        return result;
-    }
-    // Get schemes that will be provided via input (don't need mapping)
-    const schemesInInput = new Set(options.securitySchemesInInput || []);
-    // Check authProviderMapper (low risk - context-based auth)
-    if (options.authProviderMapper || schemesInInput.size > 0) {
-        result.securityRiskScore = schemesInInput.size > 0 ? 'medium' : 'low';
-        // Log info about per-scheme control
-        if (schemesInInput.size > 0) {
-            result.warnings.push(`INFO: Per-scheme security control enabled. Schemes in input: ${Array.from(schemesInInput).join(', ')}`);
-        }
-        // Validate that all schemes have mappings (except those in input)
-        for (const scheme of securitySchemes) {
-            // Skip schemes that will be provided via input
-            if (schemesInInput.has(scheme)) {
-                continue;
-            }
-            // Check if there's a mapping for this scheme
-            if (!options.authProviderMapper?.[scheme]) {
-                result.valid = false;
-                result.missingMappings.push(scheme);
-            }
-        }
-        if (!result.valid) {
-            result.warnings.push(`ERROR: Missing auth provider mappings for security schemes: ${result.missingMappings.join(', ')}`);
-        }
-        return result;
-    }
-    // No auth configuration provided - will use default ctx.authInfo.token
-    // This only works if there's a single Bearer auth scheme
-    if (securitySchemes.size > 0) {
-        result.securityRiskScore = 'medium';
-        result.warnings.push(`INFO: No auth configuration provided. Using default ctx.authInfo.token for all security schemes: ${Array.from(securitySchemes).join(', ')}`);
-        result.warnings.push('RECOMMENDATION: For multiple auth providers, use authProviderMapper or securityResolver to map each security scheme to the correct auth provider.');
-    }
-    return result;
-}
-/**
- * Resolve security for an OpenAPI tool with validation
- *
- * @param tool - OpenAPI tool with mapper
- * @param ctx - FrontMCP request context with authInfo, sessionId, traceId, etc.
- * @param options - Adapter options with auth configuration
- * @returns Resolved security (headers, query params, etc.)
- * @throws Error if security cannot be resolved
- */
-async function resolveToolSecurity(tool, ctx, options) {
-    const securityResolver = new mcp_from_openapi_1.SecurityResolver();
-    const securityContext = await createSecurityContextFromAuth(tool, ctx, options);
-    // Validate that we have auth for this tool
-    const hasAuth = securityContext.jwt ||
-        securityContext.apiKey ||
-        securityContext.basic ||
-        securityContext.oauth2Token ||
-        (securityContext.apiKeys && Object.keys(securityContext.apiKeys).length > 0) ||
-        (securityContext.customHeaders && Object.keys(securityContext.customHeaders).length > 0);
-    // Check if this tool requires security
-    // A tool requires security ONLY if a mapper has security with required=true
-    // Optional security schemes (required=false or undefined) should not block requests
-    const requiresSecurity = tool.mapper.some((m) => m.security && m.required === true);
-    if (requiresSecurity && !hasAuth) {
-        // Extract required security scheme names for error message
-        const requiredSchemes = tool.mapper
-            .filter((m) => m.security && m.required === true)
-            .map((m) => m.security?.scheme ?? 'unknown');
-        const uniqueSchemes = [...new Set(requiredSchemes)];
-        const schemesStr = uniqueSchemes.join(', ') || 'unknown';
-        const firstScheme = uniqueSchemes[0] || 'BearerAuth';
-        throw new Error(`Authentication required for tool '${tool.name}' but no auth configuration found.\n` +
-            `Required security schemes: ${schemesStr}\n` +
-            `Solutions:\n` +
-            `  1. Add authProviderMapper: { '${firstScheme}': (ctx) => ctx.authInfo.user?.token }\n` +
-            `  2. Add securityResolver: (tool, ctx) => ({ jwt: ctx.authInfo.token })\n` +
-            `  3. Add staticAuth: { jwt: process.env.API_TOKEN }\n` +
-            `  4. Set generateOptions.includeSecurityInInput: true (not recommended for production)`);
-    }
-    return await securityResolver.resolve(tool.mapper, securityContext);
-}
-//# sourceMappingURL=openapi.security.js.map