@cap-js/ord 1.2.0 → 1.3.1

package/LICENSE

@@ -198,4 +198,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

package/README.md

@@ -1,18 +1,16 @@
-[![REUSE status](https://api.reuse.software/badge/github.com/cap-js/ord)](https://api.reuse.software/info/github.com/cap-js/cds-plugin-for-ord)
+[![REUSE status](https://api.reuse.software/badge/github.com/cap-js/ord)](https://api.reuse.software/info/github.com/cap-js/ord)
 
 # CDS Plugin for ORD
 
 ## About this project
 
-This plugin adds support for the [Open Resource Discovery](https://sap.github.io/open-resource-discovery/) (ORD) protocol for CAP based applications.
+This plugin adds support for the [Open Resource Discovery](https://open-resource-discovery.github.io/specification/) (ORD) protocol for CAP based applications.
 When you add the ORD plugin, your application gains a single entry point, which allows to discover and gather machine-readable information or metadata about the application.
 You can use this information to construct a static metadata catalog or to perform a detailed runtime inspection of your actual system instances / system landscapes.
 
-For more information, have a look at the [Open Resource Discovery](https://sap.github.io/open-resource-discovery/) page.
+For more information, have a look at the [Open Resource Discovery](https://open-resource-discovery.github.io/specification/) page.
 
-> ⚠ By installing this plugin, the metadata describing your CAP application will be made openly accessible. 
-> 
-> If you have a need to protect your metadata, please refrain from installing this plugin until we support metadata protection (planned).
+> ⚠ By installing this plugin, the metadata describing your CAP application will be made openly accessible. If you want to secure your CAP application's metadata, configure `basic` authentication by setting the environment variables or updating the `.cdsrc.json` file. The plugin prioritizes environment variables, then checks `.cdsrc.json`. If neither is configured, metadata remains publicly accessible.
 
 ## Requirements and Setup
 
@@ -22,6 +20,84 @@ For more information, have a look at the [Open Resource Discovery](https://sap.g
 npm install @cap-js/ord
 ```
 
+> Note: `@cap-js/openapi` and `@cap-js/asyncapi` packages have been migrated from peerDependencies to dependencies in `package.json`. As a result, using globally installed packages may lead to conflicts. If conflicts arises do `npm uninstall -g @cap-js/openapi @cap-js/asyncapi` and then `npm install` in your project directory.
+
+### Authentication
+
+To enforce authentication in the ORD Plugin, set the following environment variables:
+
+- `ORD_AUTH_TYPE`: Specifies the authentication types.
+- `BASIC_AUTH`: Contains credentials for `basic` authentication.
+
+If `ORD_AUTH_TYPE` is not set, the application starts without authentication. This variable accepts `open` and `basic` (UCL-mTLS is also planned).
+
+> Note: `open` cannot be combined with `basic` or any other (future) authentication types.
+
+#### Open
+
+The `open` authentication type bypasses authentication checks.
+
+#### Basic Authentication
+
+The server supports Basic Authentication through an environment variable that contains a JSON string mapping usernames to bcrypt-hashed passwords:
+
+```bash
+BASIC_AUTH='{"admin":"***"}'
+```
+
+Alternatively, configure authentication in `.cdsrc.json`:
+
+```json
+"authentication": {
+    "types": ["basic"],
+    "credentials": {
+        "admin": "***"
+    }
+}
+```
+
+To generate bcrypt hashes, use the [htpasswd](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) utility:
+
+```bash
+htpasswd -Bnb <user> <password>
+```
+
+This will output something like `admin:$2y$05$...` - use only the hash part (starting with `$2y$`) in your `BASIC_AUTH` JSON.
+
+> [!IMPORTANT]
+> Make sure to use strong passwords and handle the BASIC_AUTH environment variable securely. Never commit real credentials or .env files to version control.
+
+<details>
+<summary>Using htpasswd in your environment</summary>
+
+- **Platform independent**:
+
+    > Prerequisite is to have [NodeJS](https://nodejs.org/en) installed on the machine.
+
+    ```bash
+    npm install -g htpasswd
+    ```
+
+    After installing package globally, command `htpasswd` should be available in the Terminal.
+
+- **macOS**:
+
+    Installation of any additional packages is not required. Utility `htpasswd` is available in Terminal by default.
+
+- **Linux**:
+
+    Install apache2-utils package:
+
+    ```bash
+    # Debian/Ubuntu
+    sudo apt-get install apache2-utils
+
+    # RHEL/CentOS
+    sudo yum install httpd-tools
+    ```
+
+</details>
+
 ### Usage
 
 #### Programmatic API
@@ -32,12 +108,26 @@ require("@cap-js/ord");
 ```
 
 ```js
-const csn = await cds.load(cds.env.folders.srv);
+const csn = cds.context?.model || cds.model;
 const ord = cds.compile.to.ord(csn);
 ```
 
 #### Command Line
 
+Build all ord related documents, including ordDocument and services resources files:
+
+```sh
+cds build --for ord
+
+# By default, it will be generated in /gen/ord dir, e.g.:
+# done > wrote output to:
+#    gen/ord/ord-document.json
+#    gen/ord/sap.sample:apiResource:AdminService:v1/AdminService.edmx
+#    gen/ord/sap.sample:apiResource:AdminService:v1/AdminService.oas3.json
+```
+
+Only compile ord document:
+
 ```sh
 cds compile <path to srv folder> --to ord [-o] [destinationFilePath]
 ```
@@ -47,7 +137,7 @@ cds compile <path to srv folder> --to ord [-o] [destinationFilePath]
 #### ORD Endpoints
 
 1. Run `cds watch` in the application's root.
-2. Check the following relative paths for ORD information - `/.well-known/open-resource-discovery` , `/open-resource-discovery/v1/documents/1`.
+2. Check the following relative paths for ORD information - `/.well-known/open-resource-discovery` , `/ord/v1/documents/ord-document`.
 
 <img width="1300" alt="Sample Application Demo" style="border-radius:0.5rem;" src="./asset/etc/ordEndpoint.gif">
 
@@ -55,6 +145,24 @@ cds compile <path to srv folder> --to ord [-o] [destinationFilePath]
 
 You can find more information, such as how to customize the ORD Document, in this [document](./docs/ord.md).
 
+## How to setup dev environment and run xmpl locally
+
+1. **Install dependency**
+    ```sh
+    npm i
+    ```
+2. **Run xmpl application**
+
+    ```sh
+    cd xmpl/
+
+    # watch xmpl application
+    cds watch
+
+    # build resources files
+    cds build --for ord
+    ```
+
 ## Support, Feedback, Contributing
 
 This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/cap-js/ord/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md).

package/cds-plugin.js

@@ -1,17 +1,26 @@
-require("./lib/plugin");
 const cds = require("@sap/cds");
+const { getAuthConfig } = require("./lib/authentication");
+
+if (cds.cli.command === "build") {
+    cds.build?.register?.("ord", require("./lib/build"));
+}
+
+// load auth config before any service is started
+cds.on("bootstrap", async () => {
+    getAuthConfig();
+});
 
 function _lazyRegisterCompileTarget() {
-  const ord = require("./lib/index").ord;
-  Object.defineProperty(this, "ord", { ord });
-  return ord;
+    const ord = require("./lib/index").ord;
+    Object.defineProperty(this, "ord", { ord });
+    return ord;
 }
 
 const registerORDCompileTarget = () => {
-  Object.defineProperty(cds.compile.to, "ord", {
-    get: _lazyRegisterCompileTarget,
-    configurable: true,
-  });
+    Object.defineProperty(cds.compile.to, "ord", {
+        get: _lazyRegisterCompileTarget,
+        configurable: true,
+    });
 };
 
 registerORDCompileTarget();

package/data/well-known.json

@@ -2,7 +2,7 @@
     "openResourceDiscoveryV1": {
         "documents": [
             {
-                "url": "/open-resource-discovery/v1/documents/1",
+                "url": "/ord/v1/documents/ord-document",
                 "accessStrategies": [
                     {
                         "type": "open"
@@ -11,4 +11,4 @@
             }
         ]
     }
-}
+}

package/lib/authentication.js

@@ -0,0 +1,153 @@
+const cds = require("@sap/cds");
+const { AUTHENTICATION_TYPE, BASIC_AUTH_HEADER_KEY, AUTH_TYPE_ORD_ACCESS_STRATEGY_MAP } = require("./constants");
+const { Logger } = require("./logger");
+const bcrypt = require("bcrypt");
+
+/**
+ * Compares a plain text password with a hashed password
+ * @param {string} password Plain text password to check
+ * @param {string} hashedPassword Hashed password to compare against
+ * @returns {Promise<boolean>} Promise resolving to true if passwords match, false otherwise
+ */
+async function _comparePassword(password, hashedPassword) {
+    if (!password || !hashedPassword) {
+        throw new Error("Password and hashed password are required");
+    }
+    return await bcrypt.compare(password, hashedPassword.replace(/^\$2y/, "$2a"));
+}
+
+/**
+ * Validates if a string is a bcrypt hash
+ * @param {string} hash String to validate
+ * @returns {boolean} boolean indicating if the string is a bcrypt hash
+ */
+function _isBcryptHash(hash) {
+    return /^\$2[ayb]\$\d{2}\$[A-Za-z0-9./]{53}$/.test(hash);
+}
+
+/**
+ * Create authentication configuration based on data given in the environment variables.
+ * @returns {Object} Authentication configuration object or default configuration object as a fallback.
+ */
+function createAuthConfig() {
+    const defaultAuthConfig = {
+        types: [AUTHENTICATION_TYPE.Open],
+        accessStrategies: [{ type: AUTHENTICATION_TYPE.Open }],
+    };
+
+    try {
+        const authConfig = {};
+
+        authConfig.types = process.env.ORD_AUTH_TYPE
+            ? [...new Set(JSON.parse(process.env.ORD_AUTH_TYPE))]
+            : [...new Set(cds.env.authentication?.types)];
+
+        if (!authConfig.types || authConfig.types.length === 0) {
+            Logger.error("createAuthConfig:", 'No authorization type is provided. Defaulting to "Open" authentication');
+            return defaultAuthConfig;
+        }
+
+        if (authConfig.types.some((authType) => !Object.values(AUTHENTICATION_TYPE).includes(authType))) {
+            return Object.assign(defaultAuthConfig, { error: "Invalid authentication type" });
+        }
+
+        if (
+            authConfig.types.includes(AUTHENTICATION_TYPE.Open) &&
+            authConfig.types.includes(AUTHENTICATION_TYPE.Basic)
+        ) {
+            return Object.assign(defaultAuthConfig, {
+                error: "Open authentication cannot be combined with any other authentication type",
+            });
+        }
+
+        if (authConfig.types.includes(AUTHENTICATION_TYPE.Basic)) {
+            const credentials = process.env.BASIC_AUTH
+                ? JSON.parse(process.env.BASIC_AUTH)
+                : cds.env.authentication.credentials;
+
+            // Check all passwords in credentials map
+            for (const [username, password] of Object.entries(credentials)) {
+                if (!_isBcryptHash(password)) {
+                    Logger.error("createAuthConfig:", `Password for user "${username}" must be a bcrypt hash`);
+                    return Object.assign(defaultAuthConfig, { error: "All passwords must be bcrypt hashes" });
+                }
+            }
+            // Store the complete credentials map
+            authConfig.credentials = credentials;
+        }
+        authConfig.accessStrategies = authConfig.types.map((type) => ({
+            type: AUTH_TYPE_ORD_ACCESS_STRATEGY_MAP[type],
+        }));
+        return authConfig;
+    } catch (error) {
+        return Object.assign(defaultAuthConfig, { error: error.message });
+    }
+}
+
+/**
+ * Validate, store authentication configuration in cds.context if undefined, and return the context.
+ */
+function getAuthConfig() {
+    if (cds.context?.authConfig) return cds.context?.authConfig;
+
+    const authConfig = createAuthConfig();
+
+    if (authConfig.error) {
+        Logger.error("Authentication configuration error: " + authConfig.error);
+        throw new Error("Invalid authentication configuration");
+    }
+
+    // set the context
+    cds.context = {
+        authConfig,
+    };
+    return cds.context?.authConfig;
+}
+
+/**
+ * Middleware to authenticate the request based on the authentication configuration.
+ */
+async function authenticate(req, res, next) {
+    const authConfig = cds.context.authConfig;
+
+    if (authConfig.types.includes(AUTHENTICATION_TYPE.Open)) {
+        res.status(200);
+        return next();
+    }
+
+    if (
+        !Object.keys(req.headers).includes(BASIC_AUTH_HEADER_KEY) &&
+        authConfig.types.includes(AUTHENTICATION_TYPE.Basic)
+    ) {
+        return res.status(401).setHeader("WWW-Authenticate", 'Basic realm="401"').send("Authentication required.");
+    }
+
+    if (req.headers[BASIC_AUTH_HEADER_KEY] && authConfig.types.includes(AUTHENTICATION_TYPE.Basic)) {
+        const authHeader = req.headers[BASIC_AUTH_HEADER_KEY];
+
+        if (!authHeader.startsWith("Basic ")) {
+            return res.status(401).send("Invalid authentication type");
+        }
+
+        const [username, password] = Buffer.from(authHeader.split(" ")[1], "base64").toString().split(":");
+        const credentials = authConfig.credentials;
+        const storedPassword = credentials[username];
+
+        if (storedPassword && (await _comparePassword(password, storedPassword))) {
+            res.status(200);
+            return next();
+        } else {
+            return res.status(401).send("Invalid credentials");
+        }
+    }
+
+    // In other cases, the request is unauthorized.
+    // TODO: Add support for UCL-mTLS authorization.
+    return res.status(401).send("Not authorized");
+}
+
+module.exports = {
+    authenticate,
+    createAuthConfig,
+    getAuthConfig,
+};

package/lib/build.js

@@ -0,0 +1,85 @@
+const cds = require("@sap/cds");
+const cds_dk = require("@sap/cds-dk");
+const path = require("path");
+const _ = require("lodash");
+const { ord, getMetadata } = require("./index");
+const { BUILD_DEFAULT_PATH, ORD_SERVICE_NAME, ORD_DOCUMENT_FILE_NAME } = require("./constants");
+
+module.exports = class OrdBuildPlugin extends cds_dk.build.Plugin {
+    static taskDefaults = { src: cds.env.folders.srv };
+
+    init() {
+        this.task.dest = path.join(cds.root, BUILD_DEFAULT_PATH);
+    }
+
+    async _writeResourcesFiles(resObj, model, promises) {
+        for (const resource of resObj) {
+            if (resource.ordId.includes(ORD_SERVICE_NAME) || !resource.resourceDefinitions) {
+                continue;
+            }
+
+            for (const resourceDefinition of resource.resourceDefinitions) {
+                const url = resourceDefinition.url;
+                const fileName = path.join(resource.ordId, url.split("/").pop());
+                try {
+                    const { _, response } = await getMetadata(url, model); // eslint-disable-line no-unused-vars
+                    promises.push(
+                        this.write(response)
+                            .to(fileName.replace(/:/g, "_"))
+                            .catch((err) => {
+                                console.log("Error", `Failed to write file ${fileName}: ${err.message}`);
+                            }),
+                    );
+                } catch (error) {
+                    console.log("Error", `Failed to get metadata for ${url}: ${error.message}`);
+                }
+            }
+        }
+    }
+
+    postProcess(ordDocument) {
+        const clonedOrdDocument = _.cloneDeep(ordDocument);
+        const _updateResourceUrls = (resources) => {
+            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;
+                    }
+                }
+            }
+        };
+
+        _updateResourceUrls(clonedOrdDocument.apiResources);
+        _updateResourceUrls(clonedOrdDocument.eventResources);
+
+        return clonedOrdDocument;
+    }
+
+    _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("/"));
+    }
+
+    async build() {
+        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));
+
+        if (ordDocument.apiResources && 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);
+        }
+
+        return Promise.all(promises);
+    }
+};

package/lib/constants.js

@@ -1,39 +1,115 @@
+const AUTHENTICATION_TYPE = Object.freeze({
+    Open: "open",
+    Basic: "basic",
+});
+
+const BASIC_AUTH_HEADER_KEY = "authorization";
+
+const BUILD_DEFAULT_PATH = "gen/ord";
+
+const BLOCKED_SERVICE_NAME = Object.freeze({
+    MTXServices: "cds.xt.MTXServices",
+});
+
+const ORD_ACCESS_STRATEGY = Object.freeze({
+    Open: "open",
+    Basic: "sap.businesshub:basic-auth:v1",
+});
+
+const AUTH_TYPE_ORD_ACCESS_STRATEGY_MAP = Object.freeze({
+    [AUTHENTICATION_TYPE.Open]: ORD_ACCESS_STRATEGY.Open,
+    [AUTHENTICATION_TYPE.Basic]: ORD_ACCESS_STRATEGY.Basic,
+});
+
+const CDS_ELEMENT_KIND = Object.freeze({
+    action: "action",
+    annotation: "annotation",
+    context: "context",
+    function: "function",
+    entity: "entity",
+    event: "event",
+    service: "service",
+    type: "type",
+});
+
 const COMPILER_TYPES = Object.freeze({
     oas3: "oas3",
     asyncapi2: "asyncapi2",
     edmx: "edmx",
+    csn: "csn",
 });
 
 const CONTENT_MERGE_KEY = "ordId";
 
+const DATA_PRODUCT_ANNOTATION = "@DataIntegration.dataProduct.type";
+
+const DATA_PRODUCT_TYPE = Object.freeze({
+    primary: "primary",
+});
+
 const DESCRIPTION_PREFIX = "Description for ";
 
+const ENTITY_RELATIONSHIP_ANNOTATION = "@EntityRelationship.entityType";
+
+const LEVEL = Object.freeze({
+    aggregate: "aggregate",
+    rootEntity: "root-entity",
+    subEntity: "sub-entity",
+});
+
 const OPEN_RESOURCE_DISCOVERY_VERSION = "1.9";
 
 const ORD_EXTENSIONS_PREFIX = "@ORD.Extensions.";
 
+const ORD_ODM_ENTITY_NAME_ANNOTATION = "@ODM.entityName";
+
+const ORD_EXISTING_PRODUCT_PROPERTY = "existingProductORDId";
+
 const ORD_RESOURCE_TYPE = Object.freeze({
-    service: "service",
-    entity: "entity",
-    event: "event",
     api: "api",
+    event: "event",
+    integrationDependency: "integrationDependency",
+    entityType: "entityType",
 });
 
+const ORD_SERVICE_NAME = "OpenResourceDiscoveryService";
+
+const ORD_DOCUMENT_FILE_NAME = "ord-document.json";
+
 const RESOURCE_VISIBILITY = Object.freeze({
     public: "public",
     internal: "internal",
     private: "private",
 });
 
-const SHORT_DESCRIPTION_PREFIX = "Short description for ";
+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-]+)*))?$/;
 
 module.exports = {
+    AUTHENTICATION_TYPE,
+    AUTH_TYPE_ORD_ACCESS_STRATEGY_MAP,
+    BASIC_AUTH_HEADER_KEY,
+    BUILD_DEFAULT_PATH,
+    BLOCKED_SERVICE_NAME,
+    CDS_ELEMENT_KIND,
     COMPILER_TYPES,
     CONTENT_MERGE_KEY,
+    DATA_PRODUCT_ANNOTATION,
+    DATA_PRODUCT_TYPE,
     DESCRIPTION_PREFIX,
+    ENTITY_RELATIONSHIP_ANNOTATION,
+    LEVEL,
     OPEN_RESOURCE_DISCOVERY_VERSION,
+    ORD_ACCESS_STRATEGY,
+    ORD_DOCUMENT_FILE_NAME,
     ORD_EXTENSIONS_PREFIX,
+    ORD_ODM_ENTITY_NAME_ANNOTATION,
+    ORD_EXISTING_PRODUCT_PROPERTY,
     ORD_RESOURCE_TYPE,
+    ORD_SERVICE_NAME,
     RESOURCE_VISIBILITY,
     SHORT_DESCRIPTION_PREFIX,
+    SEM_VERSION_REGEX,
 };

package/lib/date.js

@@ -1,22 +1,17 @@
-function getRFC3339Date(includeOffset = true) {
+function getRFC3339Date() {
     const now = new Date();
     const year = now.getUTCFullYear();
-    const month = String(now.getUTCMonth() + 1).padStart(2, '0');
-    const day = String(now.getUTCDate()).padStart(2, '0');
-    const hours = String(now.getUTCHours()).padStart(2, '0');
-    const minutes = String(now.getUTCMinutes()).padStart(2, '0');
-    const seconds = String(now.getUTCSeconds()).padStart(2, '0');
-    
-    if (includeOffset) {
-        const offsetHours = '01';
-        const offsetMinutes = '00';
-        const offsetSign = '+';
-        return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}${offsetSign}${offsetHours}:${offsetMinutes}`;
-    } else {
-        return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}Z`;
-    }
+    const month = String(now.getUTCMonth() + 1).padStart(2, "0");
+    const day = String(now.getUTCDate()).padStart(2, "0");
+    const hours = String(now.getUTCHours()).padStart(2, "0");
+    const minutes = String(now.getUTCMinutes()).padStart(2, "0");
+    const seconds = String(now.getUTCSeconds()).padStart(2, "0");
+    const offsetHours = "01";
+    const offsetMinutes = "00";
+    const offsetSign = "+";
+    return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}${offsetSign}${offsetHours}:${offsetMinutes}`;
 }
 
 module.exports = {
-    getRFC3339Date
+    getRFC3339Date,
 };