{"id":19755849,"url":"https://github.com/cap-js/ord","last_synced_at":"2026-02-05T19:03:02.392Z","repository":{"id":243021490,"uuid":"740880190","full_name":"cap-js/ord","owner":"cap-js","description":"Open Resource Discovery (ORD) is a protocol that allows applications and services to self-describe their exposed resources and capabilities. This plugin enables generation of ORD document for CAP based applications.","archived":false,"fork":false,"pushed_at":"2026-01-14T18:50:19.000Z","size":59608,"stargazers_count":5,"open_issues_count":24,"forks_count":8,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-01-14T22:57:24.061Z","etag":null,"topics":["plugin"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cap-js.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-01-09T09:01:07.000Z","updated_at":"2026-01-14T18:49:20.000Z","dependencies_parsed_at":"2024-07-25T08:33:53.229Z","dependency_job_id":"f352f52e-1282-4779-8023-418adaa59edb","html_url":"https://github.com/cap-js/ord","commit_stats":null,"previous_names":["cap-js/ord"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/cap-js/ord","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cap-js%2Ford","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cap-js%2Ford/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cap-js%2Ford/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cap-js%2Ford/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cap-js","download_url":"https://codeload.github.com/cap-js/ord/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cap-js%2Ford/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28513924,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["plugin"],"created_at":"2024-11-12T03:13:41.587Z","updated_at":"2026-02-05T19:03:02.384Z","avatar_url":"https://github.com/cap-js.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![REUSE status](https://api.reuse.software/badge/github.com/cap-js/ord)](https://api.reuse.software/info/github.com/cap-js/ord)\n\n# CDS Plugin for ORD\n\n## About this project\n\nThis plugin adds support for the [Open Resource Discovery](https://open-resource-discovery.github.io/specification/) (ORD) protocol for CAP based applications.\nWhen 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.\nYou can use this information to construct a static metadata catalog or to perform a detailed runtime inspection of your actual system instances / system landscapes.\n\nFor more information, have a look at the [Open Resource Discovery](https://open-resource-discovery.github.io/specification/) page.\n\n\u003e ⚠ 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.\n\n## Requirements and Setup\n\n### Installation\n\n```sh\nnpm install @cap-js/ord\n```\n\n\u003e 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.\n\n### Authentication\n\nThe ORD Plugin supports multiple authentication strategies that can be configured through environment variables or `.cdsrc.json`. Authentication types are automatically detected based on the presence of their configuration - no explicit `types` array is needed.\n\n**Supported Authentication Methods:**\n\n- **Open**: No authentication (default when no other auth is configured)\n- **Basic**: HTTP Basic Authentication with bcrypt-hashed passwords\n- **CF mTLS**: Cloud Foundry mutual TLS authentication\n\n**Multiple Authentication Strategies**: You can configure multiple authentication methods simultaneously (e.g., both `basic` and `cf-mtls`). The plugin implements an Express-like middleware pattern that tries each configured strategy in order until one succeeds.\n\n\u003e Note: When any secure authentication method is configured, open authentication is automatically disabled to ensure security. The ORD document will reflect all active authentication strategies.\n\n#### Open\n\nThe `open` authentication type is the default and bypasses authentication checks. It is automatically used when no other authentication is configured.\n\n#### Basic Authentication\n\nConfigure Basic Authentication using environment variables or `.cdsrc.json`:\n\n**Option 1: Environment Variable**\n\n```bash\nBASIC_AUTH='{\"admin\":\"$2y$05$...\"}'\n```\n\n**Option 2: Configuration File**\n\nAdd to your `.cdsrc.json`:\n\n```json\n{\n    \"cds\": {\n        \"ord\": {\n            \"authentication\": {\n                \"basic\": {\n                    \"credentials\": {\n                        \"admin\": \"$2y$05$...\"\n                    }\n                }\n            }\n        }\n    }\n}\n```\n\nTo generate bcrypt hashes, use the [htpasswd](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) utility:\n\n```bash\nhtpasswd -Bnb \u003cuser\u003e \u003cpassword\u003e\n```\n\nThis will output something like `admin:$2y$05$...` - use only the hash part (starting with `$2y$`) in your `BASIC_AUTH` JSON.\n\n\u003e [!IMPORTANT]\n\u003e Make sure to use strong passwords and handle the BASIC_AUTH environment variable securely. Never commit real credentials or .env files to version control.\n\n\u003cdetails\u003e\n\u003csummary\u003eUsing htpasswd in your environment\u003c/summary\u003e\n\n- **Platform independent**:\n\n    \u003e Prerequisite is to have [NodeJS](https://nodejs.org/en) installed on the machine.\n\n    ```bash\n    npm install -g htpasswd\n    ```\n\n    After installing package globally, command `htpasswd` should be available in the Terminal.\n\n- **macOS**:\n\n    Installation of any additional packages is not required. Utility `htpasswd` is available in Terminal by default.\n\n- **Linux**:\n\n    Install apache2-utils package:\n\n    ```bash\n    # Debian/Ubuntu\n    sudo apt-get install apache2-utils\n\n    # RHEL/CentOS\n    sudo yum install httpd-tools\n    ```\n\n\u003c/details\u003e\n\n#### CF mTLS Authentication\n\nConfigure Cloud Foundry mutual TLS authentication for SAP BTP Cloud Foundry environments.\n\n**Production Configuration with UCL (Recommended)**\n\nFor SAP UCL (Unified Customer Landscape) integration, enable mTLS in `.cdsrc.json` and configure UCL endpoints via environment variable:\n\n```json\n{\n    \"ord\": {\n        \"authentication\": {\n            \"cfMtls\": true\n        }\n    }\n}\n```\n\n```bash\nexport CF_MTLS_TRUSTED_CERTS='{\n  \"configEndpoints\": [\"https://your-ucl-endpoint/v1/info\"],\n  \"rootCaDn\": [\"CN=SAP Cloud Root CA,O=SAP SE,L=Walldorf,C=DE\"]\n}'\n```\n\n**Production Configuration with Custom Certificates**\n\nFor custom certificates without UCL:\n\n```bash\nexport CF_MTLS_TRUSTED_CERTS='{\n  \"certs\": [{\"issuer\": \"CN=My CA,O=MyOrg\", \"subject\": \"CN=my-service,O=MyOrg\"}],\n  \"rootCaDn\": [\"CN=My Root CA,O=MyOrg\"]\n}'\n```\n\n**Development Configuration**\n\nFor local development, configure the full mTLS settings directly in `.cdsrc.json`:\n\n```json\n{\n    \"ord\": {\n        \"authentication\": {\n            \"cfMtls\": {\n                \"certs\": [\n                    {\n                        \"issuer\": \"CN=Test CA,O=MyOrg,C=DE\",\n                        \"subject\": \"CN=test-client,O=MyOrg,C=DE\"\n                    }\n                ],\n                \"rootCaDn\": [\"CN=Test Root CA,O=MyOrg,C=DE\"]\n            }\n        }\n    }\n}\n```\n\n\u003e **Note:** For detailed CF mTLS configuration options, see the [documentation](./docs/ord.md#cf-mtls-authentication).\n\n#### Multiple Authentication Strategies\n\nYou can configure multiple authentication methods simultaneously to support different client types. Authentication types are detected automatically based on configuration presence:\n\n**Configuration in `.cdsrc.json`:**\n\n```json\n{\n  \"cds\": {\n    \"ord\": {\n      \"authentication\": {\n        \"basic\": {\n          \"credentials\": {\n            \"admin\": \"$2y$05$...\"\n          }\n        },\n        \"cfMtls\": {\n          \"certs\": [...],\n          \"rootCaDn\": [...]\n        }\n      }\n    }\n  }\n}\n```\n\n**How it works:**\n\n- Authentication types are detected based on what you configure (no `types` array needed)\n- The plugin tries each configured authentication strategy in order\n- The first strategy that successfully authenticates the request is used\n- If a request includes Basic auth headers, Basic authentication is attempted\n- If a request includes mTLS certificate headers, CF mTLS authentication is attempted\n- The ORD document automatically includes all configured authentication methods in its `accessStrategies`\n\n**Example scenarios:**\n\n- **Basic + CF mTLS**: Supports both API clients using Basic auth and services using mTLS certificates\n- **Basic only**: Only clients with valid Basic auth credentials can access\n- **CF mTLS only**: Only clients with trusted certificates can access\n\n### Usage\n\n#### Programmatic API\n\n```js\nconst cds = require(\"@sap/cds\");\nrequire(\"@cap-js/ord\");\n```\n\n```js\nconst csn = cds.context?.model || cds.model;\nconst ord = cds.compile.to.ord(csn);\n```\n\n#### Command Line\n\nBuild all ord related documents, including ordDocument and services resources files:\n\n```sh\ncds build --for ord\n\n# By default, it will be generated in /gen/ord dir, e.g.:\n# done \u003e wrote output to:\n#    gen/ord/ord-document.json\n#    gen/ord/sap.sample:apiResource:AdminService:v1/AdminService.edmx\n#    gen/ord/sap.sample:apiResource:AdminService:v1/AdminService.oas3.json\n```\n\nOnly compile ord document:\n\n```sh\ncds compile \u003cpath to srv folder\u003e --to ord [-o] [destinationFilePath]\n```\n\n\u003cimg width=\"1300\" alt=\"Sample Application Demo\" style=\"border-radius:0.5rem;\" src=\"./asset/etc/ordCLI.png\"\u003e\n\n#### ORD Endpoints\n\n1. Run `cds watch` in the application's root.\n2. Check the following relative paths for ORD information - `/.well-known/open-resource-discovery` , `/ord/v1/documents/ord-document`.\n\n\u003cimg width=\"1300\" alt=\"Sample Application Demo\" style=\"border-radius:0.5rem;\" src=\"./asset/etc/ordEndpoint.gif\"\u003e\n\n### Customizing ORD Document\n\nYou can find more information, such as how to customize the ORD Document, in this [document](./docs/ord.md).\n\n## How to setup dev environment and run xmpl locally\n\n1. **Install dependency**\n    ```sh\n    npm i\n    ```\n2. **Run xmpl application**\n\n    ```sh\n    cd xmpl/\n\n    # watch xmpl application\n    cds watch\n\n    # build resources files\n    cds build --for ord\n    ```\n\n## Support, Feedback, Contributing\n\nThis 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).\n\n## Security / Disclosure\n\nIf you find any bug that may be a security problem, please follow our instructions at [in our security policy](https://github.com/cap-js/ord/issues/security/policy) on how to report it. Please do not create GitHub issues for security-related doubts or problems.\n\nAt the current state, the plugin will expose static metadata with open access.\nThis means that the CAP resources are described and documented openly, but it does not imply that the resources themselves can be accessed.\n\nIf you have a need to protect your metadata, please refrain from installing this plugin until we support metadata protection.\n\n## Code of Conduct\n\nWe as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](https://github.com/cap-js/.github/blob/main/CODE_OF_CONDUCT.md) at all times.\n\n## Licensing\n\nCopyright 2024 SAP SE or an SAP affiliate company and cds-plugin-for-ord contributors. Please see our [LICENSE](LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/cap-js/\u003cyour-project\u003e).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcap-js%2Ford","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcap-js%2Ford","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcap-js%2Ford/lists"}