feat: protect the metadata - basic auth

CONTRIBUTING.md

@@ -40,22 +40,28 @@ The following rule governs code contributions:
 ## Development Setup
 
 As this is a CAP plugin, it is best to develop in the following calesi environment:
-```
+
+```bash
 git clone --recursive https://github.com/cap-js/calesi.git
 cd calesi
 npm i
 ```
+
 Then clone this repository inside the calesi projects plugin folder:
-```
+
+```bash
 cd plugins
 git clone https://github.com/cap-js/ORD
 cd ORD
 npm i
 ```
+
 For testing an example app is available in the `xmpl` folder:
-```
+
+```bash
 #If not already globally installed, install cds-dk
 npm install -g @sap/cds-dk
 cds w xmpl
 ```
-After the CAP app has started, open this link in your browser: http://localhost:4004/open-resource-discovery/v1/documents/1
+
+After the CAP app has started, open this link in your browser: <http://localhost:4004/.well-known/open-resource-discovery>

README.md

@@ -10,9 +10,7 @@ You can use this information to construct a static metadata catalog or to perfor
 
 For more information, have a look at the [Open Resource Discovery](https://sap.github.io/open-resource-discovery/) 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,81 @@ For more information, have a look at the [Open Resource Discovery](https://sap.g
 npm install @cap-js/ord
 ```
 
+### 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
@@ -47,7 +120,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">
 

__tests__/__snapshots__/mockedCsn.test.js.snap

@@ -36,7 +36,7 @@ exports[`Tests for ORD document generated out of mocked csn files Tests for ORD
           ],
           "mediaType": "application/json",
           "type": "openapi-v3",
-          "url": "/.well-known/open-resource-discovery/v1/api-metadata/AdminService.oas3.json",
+          "url": "/ord/v1/customer.capirebookshopordsample:apiResource:AdminService:v1/AdminService.oas3.json",
         },
         {
           "accessStrategies": [
@@ -46,7 +46,7 @@ exports[`Tests for ORD document generated out of mocked csn files Tests for ORD
           ],
           "mediaType": "application/xml",
           "type": "edmx",
-          "url": "/.well-known/open-resource-discovery/v1/api-metadata/AdminService.edmx",
+          "url": "/ord/v1/customer.capirebookshopordsample:apiResource:AdminService:v1/AdminService.edmx",
         },
       ],
       "shortDescription": "short description for test AdminService",
@@ -88,7 +88,7 @@ exports[`Tests for ORD document generated out of mocked csn files Tests for ORD
           ],
           "mediaType": "application/json",
           "type": "openapi-v3",
-          "url": "/.well-known/open-resource-discovery/v1/api-metadata/CatalogService.oas3.json",
+          "url": "/ord/v1/customer.capirebookshopordsample:apiResource:CatalogService:v1/CatalogService.oas3.json",
         },
         {
           "accessStrategies": [
@@ -98,7 +98,7 @@ exports[`Tests for ORD document generated out of mocked csn files Tests for ORD
           ],
           "mediaType": "application/xml",
           "type": "edmx",
-          "url": "/.well-known/open-resource-discovery/v1/api-metadata/CatalogService.edmx",
+          "url": "/ord/v1/customer.capirebookshopordsample:apiResource:CatalogService:v1/CatalogService.edmx",
         },
       ],
       "shortDescription": "short description for test CatalogService",
@@ -140,7 +140,7 @@ exports[`Tests for ORD document generated out of mocked csn files Tests for ORD
           ],
           "mediaType": "application/json",
           "type": "openapi-v3",
-          "url": "/.well-known/open-resource-discovery/v1/api-metadata/CinemaService.oas3.json",
+          "url": "/ord/v1/customer.capirebookshopordsample:apiResource:CinemaService:v1/CinemaService.oas3.json",
         },
         {
           "accessStrategies": [
@@ -150,7 +150,7 @@ exports[`Tests for ORD document generated out of mocked csn files Tests for ORD
           ],
           "mediaType": "application/xml",
           "type": "edmx",
-          "url": "/.well-known/open-resource-discovery/v1/api-metadata/CinemaService.edmx",
+          "url": "/ord/v1/customer.capirebookshopordsample:apiResource:CinemaService:v1/CinemaService.edmx",
         },
       ],
       "shortDescription": "short description for test CinemaService",
@@ -199,7 +199,7 @@ exports[`Tests for ORD document generated out of mocked csn files Tests for ORD
           ],
           "mediaType": "application/json",
           "type": "asyncapi-v2",
-          "url": "/.well-known/open-resource-discovery/v1/api-metadata/AdminService.asyncapi2.json",
+          "url": "/ord/v1/customer.capirebookshopordsample:eventResource:AdminService:v1/AdminService.asyncapi2.json",
         },
       ],
       "shortDescription": "short description for test AdminService",
@@ -228,7 +228,7 @@ exports[`Tests for ORD document generated out of mocked csn files Tests for ORD
           ],
           "mediaType": "application/json",
           "type": "asyncapi-v2",
-          "url": "/.well-known/open-resource-discovery/v1/api-metadata/CatalogService.asyncapi2.json",
+          "url": "/ord/v1/customer.capirebookshopordsample:eventResource:CatalogService:v1/CatalogService.asyncapi2.json",
         },
       ],
       "shortDescription": "short description for test CatalogService",
@@ -257,7 +257,7 @@ exports[`Tests for ORD document generated out of mocked csn files Tests for ORD
           ],
           "mediaType": "application/json",
           "type": "asyncapi-v2",
-          "url": "/.well-known/open-resource-discovery/v1/api-metadata/CinemaService.asyncapi2.json",
+          "url": "/ord/v1/customer.capirebookshopordsample:eventResource:CinemaService:v1/CinemaService.asyncapi2.json",
         },
       ],
       "shortDescription": "short description for test CinemaService",