@sap/cds-dk 10.1.2 → 10.2.1

package/lib/init/template/xsuaa/index.js

@@ -2,7 +2,7 @@ const cds = require('../../../cds')
 const { exists, read } = cds.utils
 const { readProject } = require('../../projectReader')
 const { merge } = require('../../merge')
-const { srv4, xsuaa: xsuaaDefault, xsuaa4, mtxSidecar4 } = require('../../registries/mta')
+const { srv4, xsuaa, mtxSidecar4 } = require('../../registries/mta')
 const KymaTemplate = require('../kyma')
 
 module.exports = class XsuaaTemplate extends require('../../plugin') {
@@ -34,32 +34,37 @@ module.exports = class XsuaaTemplate extends require('../../plugin') {
 
     async combine(facet) {
         const project = readProject(facet)
-        const { addMultitenancy, hasMultitenancy, addMta, hasMta, addKyma, isJava, srv, hasKyma } = project
+        const { affected, isJava, srv } = project
 
-        const cds = require('../../../../lib')
-        const xsSecurity = await (async () => {
-            try {
-                const models = await cds.load(cds.env.folders.srv)
-                return cds.compile.to.xsuaa(models)
-            } catch { /* ignore */ }
-        })() ?? { scopes: [], attributes: [], 'role-templates': [], 'authorities-inheritance': false }
+        let xsSecurity
+        if (affected('xsuaa', 'sample', 'multitenancy', 'extensibility')) {
+            const cds = require('../../../../lib')
+            xsSecurity = await (async () => {
+                try {
+                    const models = await cds.load(cds.env.folders.srv)
+                    return cds.compile.to.xsuaa(models)
+                } catch { /* ignore */ }
+            })() ?? { scopes: [], attributes: [], 'role-templates': [], 'authorities-inheritance': false }
 
-        const additions = xsSecurity.scopes.map(scope => ({ in: 'scopes', where: { name: scope.name } }))
-        await merge(xsSecurity).into('xs-security.json', { project, additions })
+            const additions = xsSecurity.scopes.map(scope => ({ in: 'scopes', where: { name: scope.name } }))
+            await merge(xsSecurity).into('xs-security.json', { project, additions })
+        }
 
-        if (addMta || addMultitenancy && hasMta) {
+        if (affected('mta', 'multitenancy', 'extensibility')) {
+            xsSecurity ??= exists('xs-security.json') ? await read('xs-security.json') : {}
+            const roles = xsSecurity['role-templates'] ?? []
             const additions = [], overwrites = [], relationships = []
             const { plan } = cds.cli.options
-            const xsuaa = plan ? xsuaa4(plan) : xsuaaDefault
             additions.push(xsuaa)
-            if (addMta) {
+            if (plan) overwrites.push({ item: [xsuaa, 'parameters.service-plan'], withValue: plan })
+            if (affected('mta')) {
                 const srvModule = srv4(srv.path)
                 relationships.push({
                     insert: [xsuaa, 'name'],
                     into: [srvModule, 'requires', 'name']
                 })
             }
-            if (hasMultitenancy) {
+            if (affected('multitenancy', 'mta')) {
                 const mtxSidecar = mtxSidecar4(isJava ? 'mtx/sidecar' : 'gen/mtx/sidecar')
                 overwrites.push({ item: [xsuaa, 'parameters.config.tenant-mode'], withValue: 'shared' })
                 relationships.push({
@@ -69,11 +74,11 @@ module.exports = class XsuaaTemplate extends require('../../plugin') {
             }
             if (plan) project.servicePlan = plan
 
-            project.hasRoles = xsSecurity['role-templates'].length > 0
-            project.roles = xsSecurity['role-templates'].map(role => role)
+            project.hasRoles = roles.length > 0
+            project.roles = roles
 
             if (!project.hasCustomRoleCollections) {
-                for (const role of xsSecurity['role-templates']) {
+                for (const role of roles) {
                     additions.push({
                         in: [xsuaa, 'parameters.role-collections'],
                         where: { 'role-template-references': ['XSAPPNAME'+role.name] }
@@ -93,14 +98,21 @@ module.exports = class XsuaaTemplate extends require('../../plugin') {
             }
         }
 
-        if (addKyma || addMultitenancy && hasKyma) {
-            const overwrites = addMultitenancy ? [{ item: 'xsuaa.parameters.tenant-mode', withValue: 'shared' }] : []
+        if (affected('kyma', 'multitenancy', 'extensibility')) {
+            xsSecurity ??= exists('xs-security.json') ? await read('xs-security.json') : {}
+            const roles = xsSecurity['role-templates'] ?? []
+            const overwrites = affected('multitenancy') ? [{ item: 'xsuaa.parameters.tenant-mode', withValue: 'shared' }] : []
+            const { plan } = cds.cli.options
+            if (plan) {
+                project.servicePlan = plan
+                overwrites.push({ item: 'xsuaa.servicePlanName', withValue: plan })
+            }
             await merge(__dirname, 'files/values.yaml.hbs').into('chart/values.yaml', { with: project, overwrites })
             const parameters = {
                 xsappname: `${project.appName}-{{ .Release.Namespace }}`
             }
-            if (!project.hasCustomRoleCollections && xsSecurity['role-templates'].length) {
-                parameters['role-collections'] = xsSecurity['role-templates'].map(role => ({
+            if (!project.hasCustomRoleCollections && roles.length) {
+                parameters['role-collections'] = roles.map(role => ({
                     name: `${role.name} (${project.appName} {{ .Release.Namespace }})`,
                     description: 'generated',
                     'role-template-references': [`$XSAPPNAME.${role.name}`],

package/lib/mtx/auth_manager.js

@@ -57,10 +57,16 @@ function reqParams(method, params) {
         }
         if (params.has('refreshToken')) {
             d.refresh_token = params.get('refreshToken');
-            const param = ['passcode', 'clientid'].find(param => params.has(param));
+            const param = ['passcode', 'authorizationCode', 'clientid'].find(param => params.has(param));
             if (param) {
                 ignored[param] = 'refresh token is present';
             }
+        } else if (params.has('authorizationCode')) {
+            d.grant_type = 'authorization_code';
+            d.authorization_code = params.get('authorizationCode');
+            if (params.has('codeVerifier')) d.code_verifier = params.get('codeVerifier');
+            if (params.has('redirectUri')) d.redirect_uri = params.get('redirectUri');
+            if (params.has('appTid')) d.app_tid = params.get('appTid');
         } else if (params.has('passcode')) {
             d.passcode = params.get('passcode');
         } else if (params.has('clientsecret')) {
@@ -143,7 +149,7 @@ async function postToken(req, params) {
 }
 
 async function fetchToken(params) {
-    if (params.has('token') || !(params.has('refreshToken') || params.has('passcode') || params.has('clientid') || !params.has('passcodeUrl'))) {
+    if (params.has('token') || !(params.has('refreshToken') || params.has('passcode') || params.has('authorizationCode') || params.has('clientid') || !params.has('passcodeUrl'))) {
         return;
     }
 

package/lib/mtx/browser_login.js

@@ -0,0 +1,181 @@
+const cds = require('../cds');
+const crypto = require('node:crypto');
+const http = require('node:http');
+
+const DEBUG = cds.debug('cli');
+
+// Fixed candidate ports for the loopback redirect: IAS matches redirect_uri exactly
+// (incl. port), so `http://localhost:<port>/callback` must be pre-registered. First free wins.
+const DEFAULT_PORTS = [8990, 8991, 8992, 8993, 8994];
+
+// Base64-URL without padding (PKCE, RFC 7636).
+function base64url(buffer) {
+    return buffer.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+// PKCE code_verifier + S256 code_challenge.
+function createPkce() {
+    const codeVerifier = base64url(crypto.randomBytes(32));
+    const codeChallenge = base64url(crypto.createHash('sha256').update(codeVerifier).digest());
+    return { codeVerifier, codeChallenge };
+}
+
+// Opens the URL in the default browser; returns whether a command was spawned.
+function openBrowser(url) {
+    const platform = process.platform;
+    let command, args, spawnOpts = { stdio: 'ignore', detached: true };
+    if (platform === 'darwin') {
+        command = 'open';
+        args = [url];
+    } else if (platform === 'win32') {
+        // Caret-escape cmd metacharacters (esp. `&`) so `start` doesn't truncate the URL.
+        const escaped = url.replace(/[&^|<>()%"]/g, m => '^' + m);
+        command = `start "" ${escaped}`;
+        args = [];
+        spawnOpts = { ...spawnOpts, shell: true, windowsVerbatimArguments: true };
+    } else {
+        command = 'xdg-open';
+        args = [url];
+    }
+    try {
+        const child = require('node:child_process').spawn(command, args, spawnOpts);
+        child.on('error', err => DEBUG?.(`Failed to open browser via ${command}: ${err.message}`));
+        child.unref();
+        return true;
+    } catch (err) {
+        DEBUG?.(`Failed to open browser via ${command}: ${err.message}`);
+        return false;
+    }
+}
+
+function escapeHtml(s) {
+    return String(s)
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;');
+}
+
+function htmlResponse(title, message) {
+    return `<!DOCTYPE html><html><head><meta charset="utf-8"><title>${escapeHtml(title)}</title></head>` +
+        `<body style="font-family:sans-serif;text-align:center;padding-top:3em">` +
+        `<h1>${escapeHtml(title)}</h1><p>${escapeHtml(message)}</p></body></html>`;
+}
+
+/**
+ * OAuth 2.0 Authorization Code + PKCE via a loopback redirect (RFC 8252): starts a
+ * local server on a fixed port (IAS requires an exact, pre-registered redirect_uri),
+ * opens the browser, and resolves with the authorization code.
+ *
+ * @param {object} metadata Authorization metadata from the server.
+ * @param {string} metadata.authorization_endpoint
+ * @param {string} metadata.client_id
+ * @param {string} [metadata.scope]
+ * @param {object} [options]
+ * @param {boolean} [options.noBrowser] Only print the URL instead of opening a browser.
+ * @param {number} [options.timeout] Milliseconds to wait for the redirect (default 300000).
+ * @param {number[]} [options.ports] Candidate fixed ports for the loopback server.
+ * @param {string} [options.host] Loopback host to bind/redirect to (default 'localhost').
+ * @returns {Promise<{code: string, codeVerifier: string, redirectUri: string}>}
+ */
+async function authorizeViaBrowser(metadata, { noBrowser = false, timeout = 5 * 60 * 1000, ports = DEFAULT_PORTS, host = 'localhost' } = {}) {
+    const { authorization_endpoint, client_id, scope, app_tid } = metadata;
+    if (!authorization_endpoint || !client_id) {
+        throw 'Incomplete authorization metadata received from server (missing authorization_endpoint or client_id).';
+    }
+
+    const { codeVerifier, codeChallenge } = createPkce();
+    const state = base64url(crypto.randomBytes(16));
+
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let timer;
+        const finish = (fn, arg) => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            server.close();
+            fn(arg);
+        };
+
+        const server = http.createServer((req, res) => {
+            const requestUrl = new URL(req.url, redirectBase);
+            if (requestUrl.pathname !== '/callback') {
+                res.statusCode = 404;
+                return res.end();
+            }
+            const params = requestUrl.searchParams;
+            const error = params.get('error');
+            const returnedState = params.get('state');
+            const code = params.get('code');
+
+            if (error) {
+                res.setHeader('Content-Type', 'text/html');
+                res.end(htmlResponse('Login failed', `The identity provider returned an error: ${error}.`));
+                return finish(reject, `Authorization failed: ${error}${params.get('error_description') ? ` (${params.get('error_description')})` : ''}.`);
+            }
+            if (returnedState !== state) {
+                res.statusCode = 400;
+                res.setHeader('Content-Type', 'text/html');
+                res.end(htmlResponse('Login failed', 'State mismatch. Please try again.'));
+                return finish(reject, 'Authorization failed: state mismatch (possible CSRF). Please retry the login.');
+            }
+            if (!code) {
+                res.statusCode = 400;
+                res.setHeader('Content-Type', 'text/html');
+                res.end(htmlResponse('Login failed', 'No authorization code received.'));
+                return finish(reject, 'Authorization failed: no authorization code received.');
+            }
+
+            res.setHeader('Content-Type', 'text/html');
+            res.end(htmlResponse('Login successful', 'You may now close this tab and return to the terminal.'));
+            finish(resolve, { code, codeVerifier, redirectUri });
+        });
+
+        server.on('error', err => {
+            if (err.code === 'EADDRINUSE' && candidates.length) return listenNext(); // try next port
+            finish(reject, `Failed to start local login server: ${err.message}`);
+        });
+
+        let redirectBase, redirectUri;
+        const candidates = [...ports];
+        const listenNext = () => {
+            const port = candidates.shift();
+            server.listen(port, '127.0.0.1');
+        };
+        server.on('listening', () => {
+            const { port } = server.address();
+            redirectBase = `http://${host}:${port}`;
+            redirectUri = `${redirectBase}/callback`;
+
+            const authUrl = new URL(authorization_endpoint);
+            authUrl.searchParams.set('response_type', 'code');
+            authUrl.searchParams.set('client_id', client_id);
+            authUrl.searchParams.set('redirect_uri', redirectUri);
+            authUrl.searchParams.set('code_challenge', codeChallenge);
+            authUrl.searchParams.set('code_challenge_method', 'S256');
+            authUrl.searchParams.set('state', state);
+            if (scope) authUrl.searchParams.set('scope', scope);
+            if (app_tid) authUrl.searchParams.set('app_tid', app_tid); // multi-tenant IAS client disambiguation
+
+            timer = setTimeout(
+                () => finish(reject, 'Timed out waiting for browser login. Please try again.'),
+                timeout
+            );
+            timer.unref?.();
+
+            const url = authUrl.toString();
+            if (noBrowser || !openBrowser(url)) {
+                console.log('Please open the following URL in your browser to log in:');
+                console.log(`\n  ${url}\n`);
+            } else {
+                console.log('Opening browser for single sign-on. Complete the login there to continue…');
+                DEBUG?.(`Authorization URL: ${url}`);
+            }
+            DEBUG?.(`Waiting for the authorization code on ${redirectUri}`);
+        });
+        listenNext();
+    });
+}
+
+module.exports = { authorizeViaBrowser, createPkce, openBrowser, DEFAULT_PORTS };

package/lib/mtx/params.js

@@ -175,6 +175,12 @@ class BasicParams {
         // AUTH PARAMS
         // - non-persisted
         this.passcode               = new Param('passcode',               undefined, { obfuscate: ObfuscationLevel.partial });
+        this.authorizationCode      = new Param('authorizationCode',      undefined, { obfuscate: ObfuscationLevel.partial }); // IAS SSO: auth code
+        this.codeVerifier           = new Param('codeVerifier',           undefined, { obfuscate: ObfuscationLevel.full }); // IAS SSO: PKCE verifier
+        this.redirectUri            = new Param('redirectUri',            undefined, { internal: true }); // IAS SSO: loopback redirect
+        this.noBrowser              = new Param('noBrowser',              false, { internal: true }); // IAS SSO: don't auto-open browser
+        this.port                   = new Param('port',                   undefined); // IAS SSO: fixed loopback port
+        this.appTid                 = new Param('appTid',                 undefined, { internal: true }); // IAS SSO: app_tid
         this.password               = new Param('password',               undefined, { obfuscate: ObfuscationLevel.full });
         this.clientid               = new Param('clientid',               undefined);
         this.clientsecret           = new Param('clientsecret',           undefined, { obfuscate: ObfuscationLevel.partial });

package/lib/mtx/push.js

@@ -8,6 +8,7 @@ const buildSystem = require('../build')
 
 const { buildResponseError, buildNetworkError, mtxFetch } = require('./util/request');
 const { getMessage } = require('./util/logging');
+const { bold } = require('../util/term');
 const { schemaRegex } = require('./util/urls');
 
 const JOB_STATUS = {
@@ -58,11 +59,16 @@ module.exports = class Push {
     }
 
     static getExtensionName(projectFolder) {
+        let name;
         try {
-            return require(join(projectFolder, 'package.json')).name;
+            name = require(join(projectFolder, 'package.json')).name;
         } catch (error) {
             throw getMessage(`Extension project at ${projectFolder} is missing package.json file`, { error, command: 'push' });
         }
+        if (typeof name !== 'string' || !name.trim()) {
+            throw getMessage(`Extension project at ${projectFolder} requires a non-empty ${bold('name')} in package.json`, { command: 'push' });
+        }
+        return name;
     }
 
     static async pushTgz(params, tgz, extensionName) {

package/lib/mtx/settings_manager.js

@@ -137,9 +137,10 @@ async function deriveUaaTokenUrl(params) {
 async function fetchAuthMetadata(params) {
     let fetchUrl = appUrlWith(OAUTH_META_PATH, params);
     DEBUG?.(`Trying to get authorization metadata from GET`, fetchUrl);
-    if (params.has('subdomain')) {
+    if (params.has('subdomain') || params.has('appTid')) {
         const u = new URL(fetchUrl);
-        u.searchParams.set('subdomain', params.get('subdomain'));
+        if (params.has('subdomain')) u.searchParams.set('subdomain', params.get('subdomain'));
+        if (params.has('appTid')) u.searchParams.set('app_tid', params.get('appTid'));
         fetchUrl = u.toString();
     }
     let responseData;
@@ -396,6 +397,27 @@ class SettingsManager {
                 throw 'Passcode cannot be empty';
             }
         }
+        // IAS browser SSO (Authorization Code + PKCE, loopback). Returns true if used,
+        // false to fall back to passcode entry (XSUAA).
+        async function addBrowserSso() {
+            const metadata = await fetchAuthMetadata(params);
+            if (metadata?.flow !== 'authorization_code') {
+                return false;
+            }
+            const { authorizeViaBrowser } = require('./browser_login');
+            const port = params.get('port');
+            // An explicit --app-tid wins over the server-resolved value on the authorize URL.
+            if (params.has('appTid')) metadata.app_tid = params.get('appTid');
+            const { code, codeVerifier, redirectUri } = await authorizeViaBrowser(metadata, {
+                noBrowser: params.get('noBrowser'),
+                ...(port && { ports: [Number(port)] })
+            });
+            params.set('authorizationCode', code);
+            params.set('codeVerifier', codeVerifier);
+            params.set('redirectUri', redirectUri);
+            if (metadata.app_tid) params.set('appTid', metadata.app_tid); // for the token exchange
+            return true;
+        }
         async function addAuthSettings() {
             function removeObsoleteToken() {
                 if (params.get('renewLogin') || params.get('tokenExpirationDate') <= Date.now()) {
@@ -467,8 +489,11 @@ class SettingsManager {
         }
 
         await addAuthSettings();
-        if (!logout && !params.has('token') && !params.has('refreshToken') && !params.has('passcode') && !params.has('clientsecret') && !params.has('key')) {
-            await addPasscode();
+        if (!logout && !params.has('token') && !params.has('refreshToken') && !params.has('passcode') && !params.has('authorizationCode') && !params.has('clientsecret') && !params.has('key')) {
+            // Prefer browser-based SSO (IAS); fall back to passcode entry (XSUAA).
+            if (!await addBrowserSso()) {
+                await addPasscode();
+            }
         }
     }
 

package/lib/util/cf.js

@@ -1,4 +1,5 @@
 const cp = require('child_process');
+const { X509Certificate } = require('crypto');
 const fsp = require('fs').promises;
 const os = require('os');
 const path = require('path');
@@ -13,6 +14,7 @@ const LOG = cds.log ? cds.log('cli') : console;
 const DEBUG = cds.debug('cli');
 
 const { bold, warn } = require('./term');
+const { ask4 } = require('./question');
 
 const { URLS } = require('../init/constants');
 
@@ -64,7 +66,7 @@ module.exports = new class CfUtil {
         }
     }
 
-    async curl(urlPath, queryObj, bodyObj) {
+    async curl(urlPath, queryObj, bodyObj, method = bodyObj ? 'POST' : 'GET') {
         let url = this.#target.apiEndpoint + urlPath
 
         const headers = { 'Authorization': this.#target.token }
@@ -77,9 +79,8 @@ module.exports = new class CfUtil {
             url += '?' + parts.join('&')
         }
 
-        const fetchOptions = { headers }
+        const fetchOptions = { headers, method }
         if (bodyObj) {
-            fetchOptions.method = 'POST'
             fetchOptions.headers['Content-Type'] = 'application/json'
             fetchOptions.body = JSON.stringify(bodyObj)
         }
@@ -100,7 +101,6 @@ module.exports = new class CfUtil {
         const data = text ? JSON.parse(text) : {}
 
         if (LOG._debug) {
-            const method = fetchOptions.method || 'GET'
             LOG.debug(`${method} ${url}\n${JSON.stringify({ headers: { ...headers, Authorization: 'bearer <token>' } }, null, 4)}\n${JSON.stringify(data, null, 4)}`)
         }
 
@@ -359,17 +359,24 @@ module.exports = new class CfUtil {
             }
         }
 
-        throw `Timeout occurred while getting service key ${bold(serviceKeyName)}`;
+        throw `timeout occurred while getting service key ${bold(serviceKeyName)}`;
     }
 
-    async getOrCreateServiceKey(serviceInstance, serviceKeyName, parameters, { silent = false } = {}) {
+    async getOrCreateServiceKey(serviceInstance, serviceKeyName, parameters, { silent = false, create = true } = {}) {
         const serviceKey = await this._getServiceKey(serviceInstance, serviceKeyName);
-        if (serviceKey) {
+        const expired = serviceKey?.certificate && serviceKey?.key && Date.parse(new X509Certificate(serviceKey.certificate).validTo) <= Date.now()
+        if (serviceKey && !expired) {
             DEBUG?.(`getting service key ${bold(serviceKeyName)}`)
             return serviceKey;
         }
+        if (expired) {
+            if (!create || !process.stdin.isTTY) throw `service key ${bold(serviceKeyName)} has expired`
+            await this.deleteServiceKey(serviceInstance, serviceKeyName, { silent })
+        } else if (!create) {
+            return
+        }
 
-        if (!silent) console.log(`creating service key ${bold(serviceKeyName)} - please be patient...`);
+        if (!silent && !expired) console.log(`creating service key ${bold(serviceKeyName)} - please be patient...`);
 
         const body = {
             type: 'key',
@@ -397,6 +404,35 @@ module.exports = new class CfUtil {
         throw `could not create service key ${bold(serviceKeyName)}`;
     }
 
+    async deleteServiceKey(serviceInstance, serviceKeyName, { silent = false } = {}) {
+        const query = { names: serviceKeyName, service_instance_guids: serviceInstance.guid }
+        const bindings = await this.curl('/v3/service_credential_bindings', query)
+        const binding = bindings?.resources?.find(binding => binding.name === serviceKeyName)
+        if (!binding) return
+        const bindingGuid = binding.guid
+
+        if (!await this.confirmServiceKeyDeletion(serviceKeyName)) {
+            throw `service key ${bold(serviceKeyName)} was not renewed because deletion was not confirmed`
+        }
+        if (!silent) console.log(`renewing expired service key ${bold(serviceKeyName)} - please be patient...`);
+        await this.curl(`/v3/service_credential_bindings/${encodeURIComponent(bindingGuid)}`, undefined, undefined, 'DELETE')
+
+        let counter = POLL_COUNTER
+        while (counter > 0) {
+            counter--
+            const remaining = await this.curl('/v3/service_credential_bindings', query)
+            if (!remaining?.resources?.some(binding => binding.guid === bindingGuid)) return
+            await this._sleep(POLL_DELAY)
+        }
+
+        throw `timeout occurred while deleting service key ${bold(serviceKeyName)}`
+    }
+
+    async confirmServiceKeyDeletion(serviceKeyName) {
+        const answer = await ask4([`service key ${bold(serviceKeyName)} has expired and must be deleted before it can be recreated, continue? (y/N) `])
+        return /^(y|yes)$/i.test(answer.trim())
+    }
+
     // CF V3 API treats commas in the 'names' filter as delimiters.
     // When a name contains a comma, omit it from the query and rely on client-side filtering.
     #safeNameQuery(query) {

package/lib/util/fs.js

@@ -61,8 +61,8 @@ async function copyRenderedJSON(src, dst, project) {
 /* General */
 
 function isRoot(folder) {
-    const { root, dir } = parse(folder)
-    return root === dir
+    const { root, dir, base } = parse(folder)
+    return root === dir && base === ''
 }
 
 const DEFAULT_CONCURRENCY = (() => {

package/node_modules/@cap-js/asyncapi/README.md

@@ -1,6 +1,6 @@
 [![REUSE status](https://api.reuse.software/badge/github.com/cap-js/asyncapi)](https://api.reuse.software/info/github.com/cap-js/asyncapi)
 
-# AsyncAPI 
+# AsyncAPI
 
 ## About this project
 
@@ -18,20 +18,10 @@ The `@cap-js/asyncapi` is a package that provides support for AsyncAPI document
 ### Installation
 
 ```sh
-$ npm install @cap-js/asyncapi
+npm add -D @cap-js/asyncapi
 ```
 
-### Usage
-
-```js
-const cds = require('@sap/cds')
-const { compile } = require('@cap-js/asyncapi')
-```
-
-```js
-const csn = await cds.load(cds.env.folders.srv)
-const asyncapiDocument = compile(csn)
-```
+See the [AsyncAPI guide](https://cap.cloud.sap/docs/guides/protocols/asyncapi) for the full documentation.
 
 ## Contributing
 
@@ -43,4 +33,4 @@ We as members, contributors, and leaders pledge to make participation in our com
 
 ## Licensing
 
-Copyright 2024 SAP SE or an SAP affiliate company and 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/asyncapi).
+Copyright 2026 SAP SE or an SAP affiliate company and 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/asyncapi).

package/node_modules/@cap-js/asyncapi/cds-plugin.js

@@ -0,0 +1,12 @@
+const cds = require('@sap/cds')
+const { compile, import: asyncapi } = require('./index')
+
+// monkey-patch cds.compile.to and cds.import.from directly, same pattern as cds-dk's lazy getters
+if (cds.compile?.to)  cds.compile.to.asyncapi = compile
+
+if (cds.import?.from) cds.import.from.asyncapi = async function (filepath, options = {}) {
+  const src = await cds.utils.read(filepath, 'utf-8')
+  const csn = asyncapi.asyncapi2csn(src)
+  options.inputFileKind = 'odata'
+  return csn
+}

package/node_modules/@cap-js/asyncapi/index.js

@@ -1,4 +1,5 @@
 
 module.exports = {
-    compile: require('./lib/compile')
-}
+    compile: require('./lib/compile'),
+    import: require('./lib/import')
+}

package/node_modules/@cap-js/asyncapi/lib/compile/components/messages/index.js

@@ -125,6 +125,7 @@ function eventToMessage(definition, name, presets, i18nBundle) {
 
     let messageObj = {
         name,
+        'x-service-name': definition._service.name,
         headers: {
             type: 'object',
             properties: getHeaderProperties(name)
@@ -157,8 +158,9 @@ function entriesToMessages(definitions, events, presets, i18nBundle) {
     const messages = {}
 
     events.forEach(event => {
-        let name = getEventName(event, definitions[event])
-        messages[name] = eventToMessage(definitions[event], name, presets, i18nBundle)
+        const definition = definitions[event]
+        let name = getEventName(event, definition)
+        messages[name] = eventToMessage(definition, name, presets, i18nBundle)
     })
 
     return messages

package/node_modules/@cap-js/asyncapi/lib/compile/components/schemas/definition.js

@@ -1,5 +1,6 @@
 const { addEnum } = require('./enum')
 const schemaUtils = require('./utils')
+const { makeNullable } = require('./utils')
 const { cacheAndReturn, getCache } = require('./cache')
 const { getOwnValue } = require('../../utils')
 const { toLocalizedArray } = require('./localized')
@@ -30,6 +31,7 @@ function elementsToSchema(schemaCache, definitions, entry, nullable, i18nBundle)
   const object = schemaUtils.getBaseTypeStructure('object')
   for (const [name, element] of Object.entries(entry.elements)) {
     if (getOwnValue(element, 'key')
+        || getOwnValue(element, 'notNull')
         || getOwnValue(element, '@mandatory')
         || (getOwnValue(element, '@Common.FieldControl') && getOwnValue(element['@Common.FieldControl'], '#') === 'Mandatory')
     ) {
@@ -44,7 +46,15 @@ function elementsToSchema(schemaCache, definitions, entry, nullable, i18nBundle)
       object.properties = {}
     }
 
-    object.properties[name] = addAnnotations(element, elementToSchema(schemaCache, definitions, element, i18nBundle), i18nBundle)
+    let propSchema = addAnnotations(element, elementToSchema(schemaCache, definitions, element, i18nBundle), i18nBundle)
+    if (!getOwnValue(element, 'notNull')
+        && !getOwnValue(element, 'key')
+        && !getOwnValue(element, '@mandatory')
+        && !(getOwnValue(element, '@Common.FieldControl') && getOwnValue(element['@Common.FieldControl'], '#') === 'Mandatory')
+    ) {
+      propSchema = makeNullable(propSchema)
+    }
+    object.properties[name] = propSchema
   }
 
   if (required.length) {