@cap-js/ord 1.3.14 → 1.4.1

package/lib/constants.js

@@ -1,6 +1,7 @@
 const AUTHENTICATION_TYPE = Object.freeze({
     Open: "open",
     Basic: "basic",
+    CfMtls: "cf-mtls",
 });
 
 const BASIC_AUTH_HEADER_KEY = "authorization";
@@ -15,11 +16,24 @@ const BLOCKED_SERVICE_NAME = Object.freeze({
 const ORD_ACCESS_STRATEGY = Object.freeze({
     Open: "open",
     Basic: "basic-auth",
+    CfMtls: "sap:cmp-mtls:v1",
 });
 
 const AUTH_TYPE_ORD_ACCESS_STRATEGY_MAP = Object.freeze({
     [AUTHENTICATION_TYPE.Open]: ORD_ACCESS_STRATEGY.Open,
     [AUTHENTICATION_TYPE.Basic]: ORD_ACCESS_STRATEGY.Basic,
+    [AUTHENTICATION_TYPE.CfMtls]: ORD_ACCESS_STRATEGY.CfMtls,
+});
+
+// CF mTLS default header names
+const CF_MTLS_HEADERS = Object.freeze({
+    ISSUER: "x-ssl-client-issuer-dn",
+    SUBJECT: "x-ssl-client-subject-dn",
+    ROOT_CA: "x-ssl-client-root-ca-dn",
+    // XFCC (X-Forwarded-Client-Cert) headers for proxy-verified mTLS
+    XFCC: "x-forwarded-client-cert",
+    CLIENT: "x-ssl-client",
+    CLIENT_VERIFY: "x-ssl-client-verify",
 });
 
 const CDS_ELEMENT_KIND = Object.freeze({
@@ -38,6 +52,7 @@ const COMPILER_TYPES = Object.freeze({
     asyncapi2: "asyncapi2",
     edmx: "edmx",
     csn: "csn",
+    mcp: "mcp",
 });
 
 const CONTENT_MERGE_KEY = "ordId";
@@ -98,6 +113,31 @@ const SHORT_DESCRIPTION_PREFIX = "Short description of ";
 const SEM_VERSION_REGEX =
     /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
 
+const MCP_CUSTOM_TYPE = "sap:mcp-server-card:v0";
+
+// CF mTLS Error Reasons
+const CF_MTLS_ERROR_REASON = Object.freeze({
+    NO_HEADERS: "NO_HEADERS",
+    HEADER_MISSING: "HEADER_MISSING",
+    INVALID_ENCODING: "INVALID_ENCODING",
+    XFCC_VERIFICATION_FAILED: "XFCC_VERIFICATION_FAILED",
+    CERT_PAIR_MISMATCH: "CERT_PAIR_MISMATCH",
+    ROOT_CA_MISMATCH: "ROOT_CA_MISMATCH",
+});
+
+// HTTP Configuration Constants
+const HTTP_CONFIG = Object.freeze({
+    METHOD_GET: "GET",
+    CONTENT_TYPE_JSON: "application/json",
+    MTLS_TIMEOUT_MS: 10000,
+});
+
+// Authentication String Constants
+const AUTH_STRINGS = Object.freeze({
+    BASIC_PREFIX: "Basic ",
+    WWW_AUTHENTICATE_REALM: 'Basic realm="401"',
+});
+
 module.exports = {
     AUTHENTICATION_TYPE,
     AUTH_TYPE_ORD_ACCESS_STRATEGY_MAP,
@@ -105,6 +145,7 @@ module.exports = {
     BUILD_DEFAULT_PATH,
     BLOCKED_SERVICE_NAME,
     CDS_ELEMENT_KIND,
+    CF_MTLS_HEADERS,
     COMPILER_TYPES,
     CONTENT_MERGE_KEY,
     DATA_PRODUCT_ANNOTATION,
@@ -113,6 +154,7 @@ module.exports = {
     DESCRIPTION_PREFIX,
     ENTITY_RELATIONSHIP_ANNOTATION,
     LEVEL,
+    MCP_CUSTOM_TYPE,
     OPEN_RESOURCE_DISCOVERY_VERSION,
     ORD_ACCESS_STRATEGY,
     ORD_DOCUMENT_FILE_NAME,
@@ -127,4 +169,7 @@ module.exports = {
     SUPPORTED_IMPLEMENTATIONSTANDARD_VERSIONS,
     SHORT_DESCRIPTION_PREFIX,
     SEM_VERSION_REGEX,
+    CF_MTLS_ERROR_REASON,
+    HTTP_CONFIG,
+    AUTH_STRINGS,
 };

package/lib/defaults.js

@@ -1,6 +1,5 @@
 const { OPEN_RESOURCE_DISCOVERY_VERSION, SHORT_DESCRIPTION_PREFIX, RESOURCE_VISIBILITY } = require("./constants");
 const { hasSAPPolicyLevel } = require("./utils");
-const { getAuthConfig } = require("./authentication");
 const _ = require("lodash");
 
 const packageTypes = [
@@ -139,14 +138,19 @@ module.exports = {
     apiResources: [],
     eventResources: [],
     entityTypes: [],
-    baseTemplate: {
-        openResourceDiscoveryV1: {
-            documents: [
-                {
-                    url: "/ord/v1/documents/ord-document",
-                    accessStrategies: getAuthConfig().accessStrategies,
-                },
-            ],
-        },
+    baseTemplate: (authConfig) => {
+        // Get access strategies from the provided authConfig
+        // If auth config is not available, fall back to empty array
+        const accessStrategies = authConfig?.accessStrategies || [];
+        return {
+            openResourceDiscoveryV1: {
+                documents: [
+                    {
+                        url: "/ord/v1/documents/ord-document",
+                        accessStrategies,
+                    },
+                ],
+            },
+        };
     },
 };

package/lib/extendOrdWithCustom.js

@@ -1,7 +1,7 @@
 const { CONTENT_MERGE_KEY } = require("./constants");
 const cds = require("@sap/cds");
 const fs = require("fs");
-const { Logger } = require("./logger");
+const Logger = require("./logger");
 const path = require("path");
 const _ = require("lodash");
 
@@ -19,13 +19,44 @@ function cleanNullProperties(obj) {
 function patchGeneratedOrdResources(destinationObj, sourceObj) {
     const destObj = _.keyBy(destinationObj, CONTENT_MERGE_KEY);
     const srcObj = _.keyBy(sourceObj, CONTENT_MERGE_KEY);
-    for (const ordId in srcObj) {
-        if (ordId in destObj) {
-            destObj[ordId] = _.assignWith(structuredClone(destObj[ordId]), structuredClone(srcObj[ordId]));
+
+    // Helper: extract MCP merge logic for clarity & reuse
+    const mergeMCPResource = (ordId, existingKey) => {
+        const baseKey = ordId in destObj ? ordId : existingKey;
+        if (baseKey) {
+            const base = structuredClone(destObj[baseKey]);
+            const override = structuredClone(srcObj[ordId]);
+            const merged = {
+                ...base, // preserve generated structural fields
+                ...override, // overlay custom changes
+                apiProtocol: "mcp", // enforce protocol
+                partOfPackage: base.partOfPackage || override.partOfPackage,
+                resourceDefinitions: base.resourceDefinitions || override.resourceDefinitions,
+            };
+            if (baseKey !== ordId) delete destObj[baseKey];
+            destObj[ordId] = merged;
         } else {
-            destObj[ordId] = srcObj[ordId];
+            // MCP plugin not available: do not introduce brand-new MCP resource purely from custom file
+            // This preserves contract: MCP resource only exists when plugin is available.
+            // Silently skip or log (warn) to avoid test noise.
+            // Logger.warn could be added here if desired.
+            return; // skip adding
+        }
+    };
+
+    const existingMCPKey = Object.keys(destObj).find((k) => destObj[k]?.apiProtocol === "mcp");
+
+    for (const ordId in srcObj) {
+        if (ordId.endsWith(":apiResource:mcp-server:v1")) {
+            mergeMCPResource(ordId, existingMCPKey);
+            continue;
         }
+        destObj[ordId] =
+            ordId in destObj
+                ? _.assignWith(structuredClone(destObj[ordId]), structuredClone(srcObj[ordId]))
+                : srcObj[ordId];
     }
+
     return cleanNullProperties(Object.values(destObj));
 }
 
@@ -54,10 +85,11 @@ function compareAndHandleCustomORDContentWithExistingContent(ordContent, customO
 function getCustomORDContent(appConfig) {
     if (!appConfig.env?.customOrdContentFile) return;
     const pathToCustomORDContent = path.join(cds.root, appConfig.env?.customOrdContentFile);
-    if (fs.existsSync(pathToCustomORDContent)) {
+    if (!fs.existsSync(pathToCustomORDContent)) {
         Logger.error("Custom ORD content file not found at", pathToCustomORDContent);
-        return require(pathToCustomORDContent);
+        return;
     }
+    return require(pathToCustomORDContent);
 }
 
 function extendCustomORDContentIfExists(appConfig, ordContent) {

package/lib/index.js

@@ -1,8 +1,11 @@
+/**
+ * Public API entry point for @cap-js/ord library
+ * Exposes core functionality for ORD document generation and metadata retrieval
+ *
+ * @example
+ * const { ord, getMetadata } = require('@cap-js/ord/lib');
+ */
 module.exports = {
-    defaults: require("./defaults.js"),
-    getMetadata: require("./metaData.js"),
     ord: require("./ord.js"),
-    Logger: require("./logger.js"),
-    constants: require("./constants.js"),
-    authentication: require("./authentication.js"),
+    getMetadata: require("./metaData.js"),
 };

package/lib/logger.js

@@ -1,17 +1,8 @@
 const cds = require("@sap/cds");
 
-const _debugLevel = cds.env?.DEBUG || process.env.DEBUG;
-
-function _getLogLevel(debugLevel, logLevels) {
-    return debugLevel ? logLevels.DEBUG : logLevels.WARN;
-}
-
-const level = _getLogLevel(_debugLevel, cds.log?.levels);
-
+// Unified INFO-level logging - simple and consistent across all environments
 const Logger = cds.log("ord-plugin", {
-    level,
+    level: cds.log?.levels?.INFO,
 });
 
-module.exports = {
-    Logger,
-};
+module.exports = Logger;

package/lib/mcpAdapter.js

@@ -0,0 +1,132 @@
+const Logger = require("./logger");
+const cds = require("@sap/cds");
+const path = require("path");
+
+/**
+ * MCP Plugin Adapter
+ * Provides an abstraction layer for interacting with @btp-ai/mcp-plugin
+ * This allows for easy mocking and testing without requiring the actual plugin
+ */
+
+/**
+ * Load package.json from project root
+ * @returns {Object} Package.json content
+ * @throws {Error} If package.json is not found
+ */
+function _loadPackageJson() {
+    const packageJsonPath = path.join(cds.root, "package.json");
+    if (!cds.utils.exists(packageJsonPath)) {
+        throw new Error(`package.json not found in the project root directory`);
+    }
+    return require(packageJsonPath);
+}
+
+/**
+ * Check if MCP plugin is listed in package.json dependencies
+ * @param {Function} loadPackageJsonFn - Optional function to load package.json (for testing)
+ * @returns {boolean} True if plugin is in dependencies or devDependencies
+ */
+function isMCPPluginInPackageJson(loadPackageJsonFn = _loadPackageJson) {
+    try {
+        const packageJson = loadPackageJsonFn();
+        const allDependencies = {
+            ...(packageJson.dependencies || {}),
+            ...(packageJson.devDependencies || {}),
+        };
+        const isInstalled = "@btp-ai/mcp-plugin" in allDependencies;
+        if (isInstalled) {
+            Logger.log("MCP plugin found in package.json dependencies");
+        }
+        return isInstalled;
+    } catch (error) {
+        Logger.error("Could not check package.json for MCP plugin:", error.message);
+        return false;
+    }
+}
+
+/**
+ * Check if MCP plugin is available at runtime
+ * @param {Function} resolveFunction - Optional custom resolve function for testing
+ * @returns {boolean} True if plugin is available
+ */
+function isMCPPluginAvailable(resolveFunction = require.resolve) {
+    try {
+        resolveFunction("@btp-ai/mcp-plugin");
+        Logger.log("MCP plugin is available at runtime");
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Get MCP plugin instance
+ * Returns null if plugin is not available
+ * @returns {Object|null} MCP plugin module or null
+ */
+function getMcpPlugin() {
+    if (!isMCPPluginAvailable()) {
+        return null;
+    }
+
+    try {
+        return require("@btp-ai/mcp-plugin");
+    } catch (error) {
+        Logger.error("Failed to load MCP plugin:", error.message);
+        return null;
+    }
+}
+
+/**
+ * Check if MCP plugin is ready for use (both installed and available)
+ * This function combines the logic of both isMCPPluginInPackageJson and isMCPPluginAvailable
+ * to provide a comprehensive check for MCP plugin readiness.
+ * Maintains the original AND logic: both conditions must be true.
+ *
+ * @param {Object} options - Options for checking
+ * @param {Function} options.resolveFunction - Custom resolve function for testing
+ * @param {Function} options.loadPackageJsonFn - Custom package.json loader for testing
+ * @returns {boolean} True if plugin is ready for use
+ */
+function isMCPPluginReady(options = {}) {
+    const { resolveFunction, loadPackageJsonFn } = options;
+
+    // Both conditions must be satisfied: declared in package.json AND available at runtime
+    return isMCPPluginInPackageJson(loadPackageJsonFn) && isMCPPluginAvailable(resolveFunction);
+}
+
+/**
+ * Build MCP server definition
+ * @param {Array} services - Array of CDS services
+ * @returns {Promise<Object>} MCP server definition
+ * @throws {Error} If MCP plugin is not available
+ */
+async function buildMcpServerDefinition(services = []) {
+    const plugin = getMcpPlugin();
+
+    if (!plugin) {
+        throw new Error("MCP plugin not available");
+    }
+
+    // Validate services parameter
+    if (!Array.isArray(services)) {
+        throw new Error("Services parameter must be an array");
+    }
+
+    try {
+        const { exposeMcpServerDefinitionForOrd } = require("@btp-ai/mcp-plugin/lib/utils/metadata");
+        return await exposeMcpServerDefinitionForOrd(services);
+    } catch (error) {
+        Logger.error("Failed to build MCP server definition:", error.message);
+        throw error;
+    }
+}
+
+module.exports = {
+    isMCPPluginAvailable,
+    isMCPPluginInPackageJson,
+    isMCPPluginReady,
+    getMcpPlugin,
+    buildMcpServerDefinition,
+    _loadPackageJson, // Export for testing
+};

package/lib/metaData.js

@@ -2,11 +2,12 @@ const cds = require("@sap/cds/lib");
 const { compile: openapi } = require("@cap-js/openapi");
 const { compile: asyncapi } = require("@cap-js/asyncapi");
 const { COMPILER_TYPES } = require("./constants");
-const { Logger } = require("./logger");
+const Logger = require("./logger");
 const { interopCSN } = require("./interopCsn.js");
 const cdsc = require("@sap/cds-compiler/lib/main");
+const { isMCPPluginReady, buildMcpServerDefinition } = require("./mcpAdapter");
 
-module.exports = async (url, model = null) => {
+const getMetadata = async (url, model = null) => {
     const parts = url
         ?.split("/")
         .pop()
@@ -15,13 +16,14 @@ module.exports = async (url, model = null) => {
     const compilerType = parts.pop();
     const serviceName = parts.join(".");
     const csn = model || cds.services[serviceName]?.model;
+    const compileOptions = cds.env["ord"]?.compileOptions || {};
 
     let responseFile;
     const options = { service: serviceName, as: "str", messages: [] };
     switch (compilerType) {
         case COMPILER_TYPES.oas3:
             try {
-                responseFile = openapi(csn, options);
+                responseFile = openapi(csn, { ...options, ...(compileOptions?.openapi || {}) });
             } catch (error) {
                 Logger.error("OpenApi error:", error.message);
                 throw error;
@@ -29,7 +31,7 @@ module.exports = async (url, model = null) => {
             break;
         case COMPILER_TYPES.asyncapi2:
             try {
-                responseFile = asyncapi(csn, options);
+                responseFile = asyncapi(csn, { ...options, ...(compileOptions?.asyncapi || {}) });
             } catch (error) {
                 Logger.error("AsyncApi error:", error.message);
                 throw error;
@@ -47,14 +49,33 @@ module.exports = async (url, model = null) => {
             break;
         case COMPILER_TYPES.edmx:
             try {
-                responseFile = await cds.compile(csn).to["edmx"](options);
+                responseFile = await cds.compile(csn).to["edmx"]({ ...options, ...(compileOptions?.edmx || {}) });
             } catch (error) {
                 Logger.error("Edmx error:", error.message);
                 throw error;
             }
+            break;
+        case COMPILER_TYPES.mcp:
+            if (!isMCPPluginReady()) {
+                throw new Error("MCP plugin is not available or not ready for use");
+            }
+            try {
+                // Get all available CDS services
+                const allServices = Object.values(cds.services);
+                // Generate metadata from runtime services using adapter
+                const mcpResult = await buildMcpServerDefinition(allServices);
+                // Extract only the MCP content, not the ORD metadata
+                responseFile = mcpResult.mcp;
+            } catch (error) {
+                Logger.error("MCP server definition error:", error.message);
+                throw error;
+            }
+            break;
     }
     return {
         contentType: `application/${compilerType === "edmx" ? "xml" : "json"}`,
         response: responseFile,
     };
 };
+
+module.exports = getMetadata;

package/lib/ord-service.js

@@ -1,23 +1,37 @@
 const cds = require("@sap/cds");
-const { ord, getMetadata, defaults, authentication, Logger } = require("./index.js");
+const ord = require("./ord.js");
+const getMetadata = require("./metaData.js");
+const defaults = require("./defaults.js");
+const { createAuthConfig, createAuthMiddleware } = require("./auth/authentication.js");
+const Logger = require("./logger.js");
 
 class OpenResourceDiscoveryService extends cds.ApplicationService {
-    init() {
+    async init() {
+        // Initialize authentication configuration from .cdsrc.json or environment variables
+        // CF mTLS validator is lazily initialized on first mTLS request
+        const authConfig = createAuthConfig();
+        if (authConfig.error) {
+            throw new Error(`Authentication initialization failed: ${authConfig.error}`);
+        }
+
+        // Create authentication middleware
+        const authMiddleware = createAuthMiddleware(authConfig);
+
         cds.app.get(`${this.path}`, (_, res) => {
-            return res.status(200).send(defaults.baseTemplate);
+            return res.status(200).send(defaults.baseTemplate(authConfig));
         });
 
-        cds.app.get(`/ord/v1/documents/ord-document`, authentication.authenticate, async (_, res) => {
+        cds.app.get(`/ord/v1/documents/ord-document`, authMiddleware, async (_, res) => {
             const csn = cds.context?.model || cds.model;
             const data = ord(csn);
             return res.status(200).send(data);
         });
 
-        cds.app.get(`/ord/v1/documents/:id`, authentication.authenticate, async (_, res) => {
+        cds.app.get(`/ord/v1/documents/:id`, authMiddleware, async (_, res) => {
             return res.status(404).send("404 Not Found");
         });
 
-        cds.app.get(`/ord/v1/:ordId?/:service?`, authentication.authenticate, async (req, res) => {
+        cds.app.get(`/ord/v1/:ordId?/:service?`, authMiddleware, async (req, res) => {
             try {
                 const { contentType, response } = await getMetadata(req.url);
                 return res.status(200).contentType(contentType).send(response);

package/lib/ord.js

@@ -11,18 +11,38 @@ const {
     createEntityTypeMappingsItemTemplate,
     createEventResourceTemplate,
     createGroupsTemplateForService,
+    createMCPAPIResourceTemplate,
     _propagateORDVisibility,
 } = require("./templates");
 const { extendCustomORDContentIfExists } = require("./extendOrdWithCustom");
 const { getRFC3339Date } = require("./date");
-const { getAuthConfig } = require("./authentication");
+const { createAuthConfig } = require("./auth/authentication");
+const { isMCPPluginReady } = require("./mcpAdapter");
 
-const { Logger } = require("./logger");
+const Logger = require("./logger");
 const _ = require("lodash");
 const cds = require("@sap/cds");
 const defaults = require("./defaults");
 const path = require("path");
 
+const _addMCPResourceIfAvailable = (apiResources, appConfig, packageIds, accessStrategies) => {
+    // Use comprehensive check for MCP plugin readiness
+    const shouldAddMCP = isMCPPluginReady();
+    if (shouldAddMCP) {
+        try {
+            const mcpResources = createMCPAPIResourceTemplate(appConfig, packageIds, accessStrategies);
+            // Handle both array and single object responses from MCP plugin
+            if (Array.isArray(mcpResources)) {
+                apiResources.push(...mcpResources);
+            } else if (mcpResources) {
+                apiResources.push(mcpResources);
+            }
+        } catch (error) {
+            Logger.warn("Failed to create MCP API resource:", error.message);
+        }
+    }
+};
+
 const initializeAppConfig = (csn) => {
     const packageJson = _loadPackageJson();
     const packageName = packageJson.name;
@@ -230,7 +250,7 @@ const _getEntityTypes = (appConfig, packageIds) => {
 };
 
 const _getAPIResources = (csn, appConfig, packageIds, accessStrategies) => {
-    return appConfig.apiResourceNames.flatMap((apiResourceName) =>
+    const apiResources = appConfig.apiResourceNames.flatMap((apiResourceName) =>
         createAPIResourceTemplate(
             apiResourceName,
             csn.definitions[apiResourceName],
@@ -239,6 +259,11 @@ const _getAPIResources = (csn, appConfig, packageIds, accessStrategies) => {
             accessStrategies,
         ),
     );
+
+    // Conditionally add MCP API resource if plugin is available
+    _addMCPResourceIfAvailable(apiResources, appConfig, packageIds, accessStrategies);
+
+    return apiResources;
 };
 
 const _getEventResources = (csn, appConfig, packageIds, accessStrategies) => {
@@ -322,7 +347,13 @@ function _filterUnusedPackages(ordDocument) {
 module.exports = (csn) => {
     const linkedCsn = _propagateORDVisibility(cds.linked(csn));
     const appConfig = initializeAppConfig(linkedCsn);
-    const accessStrategies = getAuthConfig().accessStrategies;
+
+    // Create auth config and fail-closed on configuration errors
+    const authConfig = createAuthConfig();
+    if (authConfig.error) {
+        throw new Error(`Authentication configuration error: ${authConfig.error}`);
+    }
+    const accessStrategies = authConfig.accessStrategies;
 
     let ordDocument = createDefaultORDDocument(linkedCsn, appConfig);
     const packageIds = extractPackageIds(ordDocument);