@cap-js/ord 1.4.2 → 1.4.3

package/README.md

@@ -114,34 +114,64 @@ This will output something like `admin:$2y$05$...` - use only the hash part (sta
 
 #### CF mTLS Authentication
 
-Configure Cloud Foundry mutual TLS authentication in `.cdsrc.json`:
+Configure Cloud Foundry mutual TLS authentication for SAP BTP Cloud Foundry environments.
+
+**Production Configuration with UCL (Recommended)**
+
+For SAP UCL (Unified Customer Landscape) integration, enable mTLS in `.cdsrc.json` and configure UCL endpoints via environment variable:
 
 ```json
 {
-    "cds": {
-        "ord": {
-            "authentication": {
-                "cfMtls": {
-                    "certs": [
-                        {
-                            "issuer": "CN=SAP PKI Certificate Service Client CA,OU=SAP BTP Clients,O=SAP SE,C=DE",
-                            "subject": "CN=my-service,OU=SAP Cloud Platform Clients,O=SAP SE,C=DE"
-                        }
-                    ],
-                    "rootCaDn": ["CN=SAP Cloud Root CA,O=SAP SE,C=DE"]
-                }
-            }
+    "ord": {
+        "authentication": {
+            "cfMtls": true
         }
     }
 }
 ```
 
-Or use the environment variable:
+```bash
+export CF_MTLS_TRUSTED_CERTS='{
+  "configEndpoints": ["https://your-ucl-endpoint/v1/info"],
+  "rootCaDn": ["CN=SAP Cloud Root CA,O=SAP SE,L=Walldorf,C=DE"]
+}'
+```
+
+**Production Configuration with Custom Certificates**
+
+For custom certificates without UCL:
 
 ```bash
-CF_MTLS_TRUSTED_CERTS='{"certs":[...],"rootCaDn":[...]}'
+export CF_MTLS_TRUSTED_CERTS='{
+  "certs": [{"issuer": "CN=My CA,O=MyOrg", "subject": "CN=my-service,O=MyOrg"}],
+  "rootCaDn": ["CN=My Root CA,O=MyOrg"]
+}'
 ```
 
+**Development Configuration**
+
+For local development, configure the full mTLS settings directly in `.cdsrc.json`:
+
+```json
+{
+    "ord": {
+        "authentication": {
+            "cfMtls": {
+                "certs": [
+                    {
+                        "issuer": "CN=Test CA,O=MyOrg,C=DE",
+                        "subject": "CN=test-client,O=MyOrg,C=DE"
+                    }
+                ],
+                "rootCaDn": ["CN=Test Root CA,O=MyOrg,C=DE"]
+            }
+        }
+    }
+}
+```
+
+> **Note:** For detailed CF mTLS configuration options, see the [documentation](./docs/ord.md#cf-mtls-authentication).
+
 #### Multiple Authentication Strategies
 
 You can configure multiple authentication methods simultaneously to support different client types. Authentication types are detected automatically based on configuration presence:

package/lib/auth/cf-mtls.js

@@ -179,26 +179,51 @@ async function createCfMtlsConfig(cds, Logger) {
         Logger.error("CF mTLS requires CF_INSTANCE_GUID environment variable");
     }
 
-    // Parse configuration from single JSON environment variable or CDS settings
+    // Configuration priority:
+    // 1. cfMtls: true - Production mode, requires CF_MTLS_TRUSTED_CERTS env var
+    // 2. cfMtls: { ... } - Development mode, uses inline config from .cdsrc.json
+    // Note: Environment variable alone is NOT sufficient, explicit .cdsrc.json declaration required
+
     let config;
+    const cdsConfig = cds.env.ord?.authentication?.cfMtls;
+
+    // cfMtls must be explicitly configured in .cdsrc.json
+    if (!cdsConfig) {
+        Logger.error("CF mTLS configuration required. Set ord.authentication.cfMtls in .cdsrc.json");
+        return {
+            error: "CF mTLS configuration required. Set ord.authentication.cfMtls in .cdsrc.json",
+        };
+    }
 
-    if (process.env.CF_MTLS_TRUSTED_CERTS) {
+    // Production: cfMtls: true → requires CF_MTLS_TRUSTED_CERTS environment variable
+    if (cdsConfig === true) {
+        if (!process.env.CF_MTLS_TRUSTED_CERTS) {
+            Logger.error(
+                "CF mTLS enabled with cfMtls: true but CF_MTLS_TRUSTED_CERTS environment variable is not set. " +
+                    "Set CF_MTLS_TRUSTED_CERTS with JSON: {certs: [...], rootCaDn: [...]} or {configEndpoints: [...], rootCaDn: [...]}",
+            );
+            return {
+                error: "CF_MTLS_TRUSTED_CERTS environment variable required when cfMtls is set to true",
+            };
+        }
         try {
             config = JSON.parse(process.env.CF_MTLS_TRUSTED_CERTS);
         } catch {
-            Logger.error("Failed to parse CF_MTLS_TRUSTED_CERTS");
+            Logger.error("Failed to parse CF_MTLS_TRUSTED_CERTS environment variable");
             return {
                 error: "Invalid CF_MTLS_TRUSTED_CERTS format. Expected JSON: {certs: [...], rootCaDn: [...], configEndpoints: [...]}",
             };
         }
-    } else {
-        config = cds.env.ord?.authentication?.cfMtls;
     }
-
-    if (!config) {
-        Logger.error("CF mTLS configuration required. Set CF_MTLS_TRUSTED_CERTS or cds.env.ord.authentication.cfMtls");
+    // Development: cfMtls: { ... } → use inline config from .cdsrc.json
+    else if (typeof cdsConfig === "object") {
+        config = cdsConfig;
+    }
+    // Invalid configuration type
+    else {
+        Logger.error("Invalid cfMtls configuration. Expected true or object with certs/rootCaDn/configEndpoints");
         return {
-            error: "CF mTLS configuration required",
+            error: "Invalid cfMtls configuration. Expected true or object",
         };
     }
 
@@ -268,7 +293,7 @@ async function createCfMtlsConfig(cds, Logger) {
     if (certs.length === 0) {
         Logger.error(
             "CF mTLS requires at least one certificate pair. " +
-                "Provide via certs array or configEndpoints in CF_MTLS_TRUSTED_CERTS or cds.env.ord.cfMtls",
+                "Provide via certs array or configEndpoints in CF_MTLS_TRUSTED_CERTS or ord.authentication.cfMtls",
         );
         return {
             error: "CF mTLS requires at least one certificate pair",
@@ -278,7 +303,7 @@ async function createCfMtlsConfig(cds, Logger) {
     if (rootCaDn.length === 0) {
         Logger.error(
             "CF mTLS requires at least one root CA. " +
-                "Provide via rootCaDn array in CF_MTLS_TRUSTED_CERTS or cds.env.ord.cfMtls",
+                "Provide via rootCaDn array in CF_MTLS_TRUSTED_CERTS or ord.authentication.cfMtls",
         );
         return {
             error: "CF mTLS requires at least one root CA",

package/lib/build.js

@@ -6,6 +6,8 @@ const cliProgress = require("cli-progress");
 const { BUILD_DEFAULT_PATH, ORD_SERVICE_NAME, ORD_DOCUMENT_FILE_NAME } = require("./constants");
 const { isMCPPluginInPackageJson } = require("./mcpAdapter");
 
+const { BuildError } = cds.build;
+
 module.exports = class OrdBuildPlugin extends cds.build.Plugin {
     static taskDefaults = { src: cds.env.folders.srv };
 
@@ -15,54 +17,46 @@ module.exports = class OrdBuildPlugin extends cds.build.Plugin {
         }
     }
 
-    async _writeResourcesFiles(resObj, model, promises) {
-        let totalFiles = resObj.reduce((total, resource) => {
-            if (!resource.ordId.includes(ORD_SERVICE_NAME) && resource.resourceDefinitions) {
-                return total + resource.resourceDefinitions.length;
-            }
-            return total;
-        }, 0);
-
+    _createProgressBar(totalFiles) {
         const progressBar = new cliProgress.SingleBar({
             format: "Processing resourcesFiles [{bar}] {percentage}% | {value}/{total} | ETA: {eta}s",
             barCompleteChar: "█",
             barIncompleteChar: "░",
             stopOnComplete: true,
         });
+        progressBar.start(totalFiles, 0);
+        return progressBar;
+    }
+
+    _countTotalFiles(resObj) {
+        return resObj.reduce((total, resource) => {
+            if (!resource.ordId.includes(ORD_SERVICE_NAME) && resource.resourceDefinitions) {
+                return total + resource.resourceDefinitions.length;
+            }
+            return total;
+        }, 0);
+    }
 
-        let warnings = [];
+    async _writeResourcesFiles(resObj, model, promises) {
+        const totalFiles = this._countTotalFiles(resObj);
+        const progressBar = this._createProgressBar(totalFiles);
         let completed = 0;
-        progressBar.start(totalFiles, 0);
 
         try {
             for (const resource of resObj) {
-                // Generate if has service definitions OR has MCP plugin
                 const shouldGenerate = resource.resourceDefinitions || isMCPPluginInPackageJson();
                 if (!shouldGenerate) continue;
+
                 for (const resourceDefinition of resource.resourceDefinitions) {
-                    try {
-                        const { _, response } = await getMetadata(resourceDefinition.url, model); // eslint-disable-line no-unused-vars
-                        const fileName = path
-                            .join(resource.ordId, resourceDefinition.url.split("/").pop())
-                            .replace(/:/g, "_");
-                        promises.push(
-                            this.write(response)
-                                .to(fileName)
-                                .catch((err) => {
-                                    warnings.push(`Error writing file ${fileName}: ${err.message}`);
-                                }),
-                        );
-                    } catch (error) {
-                        warnings.push(`Error getting metadata for ${resourceDefinition.url}: ${error.message}`);
-                    }
-                    completed++;
-                    progressBar.update(completed);
+                    const { _, response } = await getMetadata(resourceDefinition.url, model); // eslint-disable-line no-unused-vars
+                    const fileName = path
+                        .join(resource.ordId, resourceDefinition.url.split("/").pop())
+                        .replace(/:/g, "_");
+                    promises.push(this.write(response).to(fileName));
+                    progressBar.update(++completed);
                 }
             }
             await Promise.all(promises);
-        } catch (error) {
-            warnings.push("Failed to process resources: " + error.message);
-            throw error;
         } finally {
             progressBar.stop();
         }
@@ -74,9 +68,7 @@ module.exports = class OrdBuildPlugin extends cds.build.Plugin {
             for (const resource of resources || []) {
                 if (resource.resourceDefinitions) {
                     for (const resourceDefinition of resource.resourceDefinitions) {
-                        let url = resourceDefinition.url;
-                        url = this._createRelativePath(url);
-                        resourceDefinition.url = url;
+                        resourceDefinition.url = this._createRelativePath(resourceDefinition.url);
                     }
                 }
             }
@@ -91,25 +83,29 @@ module.exports = class OrdBuildPlugin extends cds.build.Plugin {
     _createRelativePath(url) {
         let relative = url.split("/ord/v1").pop();
         if (relative.startsWith("/")) relative = relative.slice(1);
-        relative = relative.replace(/:/g, "_");
-        return path.join(...relative.split("/"));
+        return path.join(...relative.replace(/:/g, "_").split("/"));
     }
 
     async build() {
-        const model = await this.model();
-        const ordDocument = ord(model);
-        const postProcessedOrdDocument = this.postProcess(ordDocument);
+        try {
+            const model = await this.model();
+            const ordDocument = ord(model);
+            const postProcessedOrdDocument = this.postProcess(ordDocument);
 
-        const promises = [];
-        promises.push(this.write(postProcessedOrdDocument).to(ORD_DOCUMENT_FILE_NAME));
+            const promises = [];
+            promises.push(this.write(postProcessedOrdDocument).to(ORD_DOCUMENT_FILE_NAME));
 
-        if (ordDocument.apiResources && ordDocument.apiResources.length > 0) {
-            await this._writeResourcesFiles(ordDocument.apiResources, model, promises);
-        }
+            if (ordDocument.apiResources?.length > 0) {
+                await this._writeResourcesFiles(ordDocument.apiResources, model, promises);
+            }
 
-        if (ordDocument.eventResources && ordDocument.eventResources.length > 0) {
-            await this._writeResourcesFiles(ordDocument.eventResources, model, promises);
+            if (ordDocument.eventResources?.length > 0) {
+                await this._writeResourcesFiles(ordDocument.eventResources, model, promises);
+            }
+
+            return Promise.all(promises);
+        } catch (error) {
+            throw new BuildError(`ORD build failed: ${error.message}`);
         }
-        return Promise.all(promises);
     }
 };

package/lib/constants.js

@@ -77,6 +77,8 @@ const LEVEL = Object.freeze({
 
 const OPEN_RESOURCE_DISCOVERY_VERSION = "1.12";
 
+const OPENAPI_SERVERS_ANNOTATION = "@OpenAPI.servers";
+
 const ORD_EXTENSIONS_PREFIX = "@ORD.Extensions.";
 
 const ORD_ODM_ENTITY_NAME_ANNOTATION = "@ODM.entityName";
@@ -156,6 +158,7 @@ module.exports = {
     LEVEL,
     MCP_CUSTOM_TYPE,
     OPEN_RESOURCE_DISCOVERY_VERSION,
+    OPENAPI_SERVERS_ANNOTATION,
     ORD_ACCESS_STRATEGY,
     ORD_DOCUMENT_FILE_NAME,
     ORD_EXTENSIONS_PREFIX,

package/lib/metaData.js

@@ -1,12 +1,24 @@
 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 { COMPILER_TYPES, OPENAPI_SERVERS_ANNOTATION } = require("./constants");
 const Logger = require("./logger");
 const { interopCSN } = require("./interopCsn.js");
 const cdsc = require("@sap/cds-compiler/lib/main");
 const { isMCPPluginReady, buildMcpServerDefinition } = require("./mcpAdapter");
 
+/**
+ * Read @OpenAPI.servers annotation from service definition
+ * @param {object} csn - The CSN model
+ * @param {string} serviceName - The service name
+ * @returns {string|undefined} - JSON string of servers array or undefined
+ */
+const _getServersFromAnnotation = (csn, serviceName) => {
+    const servers = csn?.definitions?.[serviceName]?.[OPENAPI_SERVERS_ANNOTATION];
+    const isValidServers = Array.isArray(servers) && servers.length > 0;
+    return isValidServers ? JSON.stringify(servers) : undefined;
+};
+
 const getMetadata = async (url, model = null) => {
     const parts = url
         ?.split("/")
@@ -23,7 +35,16 @@ const getMetadata = async (url, model = null) => {
     switch (compilerType) {
         case COMPILER_TYPES.oas3:
             try {
-                responseFile = openapi(csn, { ...options, ...(compileOptions?.openapi || {}) });
+                // Check for service-level @OpenAPI.servers annotation
+                const serversFromAnnotation = _getServersFromAnnotation(csn, serviceName);
+                const openapiOptions = { ...options, ...(compileOptions?.openapi || {}) };
+
+                // Service-level annotation takes precedence over global config
+                if (serversFromAnnotation) {
+                    openapiOptions["openapi:servers"] = serversFromAnnotation;
+                }
+
+                responseFile = openapi(csn, openapiOptions);
             } catch (error) {
                 Logger.error("OpenApi error:", error.message);
                 throw error;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cap-js/ord",
-    "version": "1.4.2",
+    "version": "1.4.3",
     "description": "CAP Plugin for generating ORD document.",
     "repository": "cap-js/ord",
     "author": "SAP SE (https://www.sap.com)",
@@ -23,6 +23,7 @@
         "test": "jest __tests__/unit --ci --collectCoverage",
         "test:integration:basic": "jest __tests__/integration/basic-auth.test.js --testPathIgnorePatterns=/node_modules/ --forceExit",
         "test:integration:mtls": "jest __tests__/integration/mtls-auth.test.js --testPathIgnorePatterns=/node_modules/ --forceExit",
+        "test:integration:build": "jest __tests__/integration/cds-build.test.js --testPathIgnorePatterns=/node_modules/ --forceExit",
         "update-snapshot": "jest --ci --updateSnapshot",
         "cds:version": "cds v -i"
     },
@@ -30,7 +31,7 @@
         "eslint": "^9.2.0",
         "express": "^4",
         "jest": "^30.0.0",
-        "prettier": "3.7.4",
+        "prettier": "3.8.1",
         "supertest": "^7.0.0",
         "@cap-js/sqlite": "^2",
         "@sap/cds-dk": ">=8.9.5"