@sap-ux/backend-proxy-middleware-cf 0.0.98 → 0.1.0

package/dist/config/env.js

@@ -0,0 +1,129 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAndApplyEnvOptions = loadAndApplyEnvOptions;
+exports.updateUi5ServerDestinationPort = updateUi5ServerDestinationPort;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const adp_tooling_1 = require("@sap-ux/adp-tooling");
+const constants_1 = require("./constants");
+/**
+ * Load and parse env options JSON file.
+ *
+ * @param rootPath - Project root path.
+ * @param envOptionsPath - Path to file (relative to rootPath).
+ * @returns Parsed options object.
+ */
+function loadEnvOptionsFromFile(rootPath, envOptionsPath) {
+    const resolvedPath = node_path_1.default.resolve(rootPath, envOptionsPath);
+    if (!node_fs_1.default.existsSync(resolvedPath)) {
+        throw new Error(`Env options file not found at "${resolvedPath}" (envOptionsPath: "${envOptionsPath}").`);
+    }
+    try {
+        const content = node_fs_1.default.readFileSync(resolvedPath, 'utf8');
+        return JSON.parse(content);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to read env options from "${resolvedPath}": ${message}.`);
+    }
+}
+/**
+ * Apply options to process.env with JSON-stringified destinations and VCAP_SERVICES.
+ *
+ * @param options - Env options to apply.
+ */
+function applyToProcessEnv(options) {
+    const envOptions = {
+        ...options,
+        ...(options.destinations ? { destinations: JSON.stringify(options.destinations) } : {}),
+        ...(options.VCAP_SERVICES ? { VCAP_SERVICES: JSON.stringify(options.VCAP_SERVICES) } : {})
+    };
+    Object.assign(process.env, envOptions);
+}
+/**
+ * Load env options from file or CF, apply to process.env, and add destinations from effectiveOptions.
+ *
+ * When effectiveOptions.envOptionsPath is set, loads that JSON file. When null, loads mta.yaml one level
+ * above rootPath and fetches VCAP_SERVICES from CF. effectiveOptions.destinations is applied so
+ * middleware config takes precedence over file/env.
+ *
+ * @param rootPath - Project root path.
+ * @param effectiveOptions - Merged config; envOptionsPath and destinations are used.
+ * @param logger - Logger for CF path.
+ * @returns Promise resolving when env options are loaded and applied.
+ */
+async function loadAndApplyEnvOptions(rootPath, effectiveOptions, logger) {
+    const { envOptionsPath, destinations: middlewareDestinations } = effectiveOptions;
+    let options;
+    if (envOptionsPath) {
+        const envOptions = loadEnvOptionsFromFile(rootPath, envOptionsPath);
+        const destinations = envOptions.destinations
+            ? [...envOptions.destinations, ...middlewareDestinations]
+            : middlewareDestinations;
+        options = { ...envOptions, destinations };
+    }
+    else {
+        const mtaPath = node_path_1.default.resolve(rootPath, '..', 'mta.yaml');
+        const spaceGuid = await (0, adp_tooling_1.getSpaceGuidFromUi5Yaml)(rootPath, logger);
+        if (!spaceGuid) {
+            throw new Error('No space GUID (from config or ui5.yaml). Cannot load CF env options.');
+        }
+        if (!node_fs_1.default.existsSync(mtaPath)) {
+            throw new Error(`mta.yaml not found at "${mtaPath}". Cannot load CF env options.`);
+        }
+        const mtaYaml = (0, adp_tooling_1.getYamlContent)(mtaPath);
+        const VCAP_SERVICES = await (0, adp_tooling_1.buildVcapServicesFromResources)(mtaYaml.resources, spaceGuid, logger);
+        options = {
+            VCAP_SERVICES,
+            destinations: middlewareDestinations
+        };
+    }
+    applyToProcessEnv(options);
+}
+/**
+ * Ensure the ui5-server destination exists and has the correct URL.
+ * If ui5-server doesn't exist in configuration, it will be auto-created.
+ * If it exists but has a different port, it will be updated.
+ * In BAS, the external URL is used instead of localhost so the approuter
+ * builds correct redirect URIs.
+ *
+ * This enables multi-instance support and removes the need to manually
+ * configure ui5-server in ui5.yaml - it's auto-configured based on the actual port.
+ *
+ * @param effectiveOptions - Merged options containing destinations.
+ * @param actualPort - The actual port detected from the incoming request.
+ * @param basExternalUrl - Optional BAS external URL; when set, used as the destination URL.
+ * @returns True if destination was created or updated, false if no change needed.
+ */
+function updateUi5ServerDestinationPort(effectiveOptions, actualPort, basExternalUrl) {
+    const newUrl = basExternalUrl ? basExternalUrl.href : `http://localhost:${actualPort}`;
+    let ui5ServerDest = effectiveOptions.destinations.find((d) => d.name === constants_1.UI5_SERVER_DESTINATION);
+    if (!ui5ServerDest) {
+        ui5ServerDest = { name: constants_1.UI5_SERVER_DESTINATION, url: newUrl };
+        effectiveOptions.destinations.push(ui5ServerDest);
+        const envDestinations = JSON.parse(process.env.destinations ?? '[]');
+        envDestinations.push({ name: constants_1.UI5_SERVER_DESTINATION, url: newUrl });
+        process.env.destinations = JSON.stringify(envDestinations);
+        return true;
+    }
+    const currentUrl = new URL(ui5ServerDest.url);
+    const currentPort = Number.parseInt(currentUrl.port, 10) || 80;
+    if (currentPort === actualPort) {
+        return false;
+    }
+    ui5ServerDest.url = newUrl;
+    const envDestinations = JSON.parse(process.env.destinations ?? '[]');
+    const envUi5ServerDest = envDestinations.find((d) => d.name === constants_1.UI5_SERVER_DESTINATION);
+    if (envUi5ServerDest) {
+        envUi5ServerDest.url = newUrl;
+    }
+    else {
+        envDestinations.push({ name: constants_1.UI5_SERVER_DESTINATION, url: newUrl });
+    }
+    process.env.destinations = JSON.stringify(envDestinations);
+    return true;
+}
+//# sourceMappingURL=env.js.map

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export type { CfOAuthMiddlewareConfig } from './types';
+export type { BackendProxyMiddlewareCfConfig, ApprouterDestination, ApprouterExtension } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/middleware.js

@@ -1,34 +1,101 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = __importDefault(require("node:fs"));
+const dotenv_1 = __importDefault(require("dotenv"));
+const node_path_1 = __importDefault(require("node:path"));
 const logger_1 = require("@sap-ux/logger");
-const proxy_1 = require("./proxy");
-const validation_1 = require("./validation");
-const token_1 = require("./token");
+const utils_1 = require("./utils");
+const proxy_1 = require("./proxy/proxy");
+const approuter_1 = require("./approuter/approuter");
+const extensions_1 = require("./approuter/extensions");
+const config_1 = require("./config/config");
+const xssecurity_1 = require("./platform/xssecurity");
+const bas_1 = require("./platform/bas");
+const routes_1 = require("./proxy/routes");
+const env_1 = require("./config/env");
+dotenv_1.default.config();
 /**
- * UI5 middleware for proxying requests to Cloud Foundry destinations with OAuth2 authentication.
- * Supports multiple destination URLs with their own OData source paths.
+ * UI5 server middleware: runs `@sap/approuter` and proxies matching requests to it.
+ * Uses lazy initialization to detect the actual UI5 server port from the first request,
+ * enabling multi-instance support where hardcoded ports in ui5.yaml may differ from runtime.
  *
- * @param {MiddlewareParameters<CfOAuthMiddlewareConfig>} params - Input parameters for UI5 middleware.
- * @param {CfOAuthMiddlewareConfig} params.options - Configuration options.
- * @returns {Promise<RequestHandler>} Express middleware handler.
+ * @param params - Middleware parameters from UI5 (options, middlewareUtil).
+ * @param params.options - Options containing configuration from ui5.yaml.
+ * @param params.middlewareUtil - UI5 middleware utilities (getProject, etc.).
+ * @returns Promise resolving to the proxy request handler.
  */
-module.exports = async ({ options }) => {
-    const config = options.configuration;
-    if (!config) {
+async function backendProxyMiddlewareCf({ options, middlewareUtil }) {
+    const configuration = options.configuration;
+    if (!configuration) {
         throw new Error('Backend proxy middleware (CF) has no configuration.');
     }
     const logger = new logger_1.ToolsLogger({
-        logLevel: config.debug ? logger_1.LogLevel.Debug : logger_1.LogLevel.Info,
+        logLevel: configuration.debug ? logger_1.LogLevel.Debug : logger_1.LogLevel.Info,
         transports: [new logger_1.UI5ToolingTransport({ moduleName: 'backend-proxy-middleware-cf' })]
     });
-    await (0, validation_1.validateConfig)(config, logger);
-    const tokenProvider = await (0, token_1.createTokenProvider)(config, logger);
-    // Setup proxy routes for all backends
-    const router = (0, proxy_1.setupProxyRoutes)(config.backends, tokenProvider, logger);
-    // Log initialization
-    config.backends.forEach((backend) => {
-        logger.info(`Backend proxy middleware (CF) initialized: url=${backend.url}, paths=${backend.paths.join(', ')}`);
+    const effectiveOptions = (0, config_1.mergeEffectiveOptions)(configuration);
+    process.env.WS_ALLOWED_ORIGINS = process.env.WS_ALLOWED_ORIGINS ?? JSON.stringify([{ host: 'localhost' }]);
+    process.env.XS_APP_LOG_LEVEL = process.env.XS_APP_LOG_LEVEL ?? (effectiveOptions.debug ? 'DEBUG' : 'ERROR');
+    const project = middlewareUtil.getProject();
+    const rootPath = project.getRootPath() ?? process.cwd();
+    const xsappJsonPath = node_path_1.default.resolve(rootPath, effectiveOptions.xsappJsonPath);
+    if (!node_fs_1.default.existsSync(xsappJsonPath)) {
+        throw new Error(`xs-app.json not found at "${xsappJsonPath}"`);
+    }
+    await (0, env_1.loadAndApplyEnvOptions)(rootPath, effectiveOptions, logger);
+    await (0, xssecurity_1.updateXsuaaService)(rootPath, logger);
+    const sourcePath = project.getSourcePath();
+    const xsappConfig = (0, routes_1.loadAndPrepareXsappConfig)({
+        rootPath,
+        xsappJsonPath,
+        effectiveOptions,
+        sourcePath,
+        logger
     });
-    return router;
-};
+    const { modules, routes: extensionsRoutes } = (0, extensions_1.loadExtensions)(rootPath, effectiveOptions.extensions, logger);
+    const port = await (0, utils_1.nextFreePort)(effectiveOptions.port, logger);
+    if (port !== effectiveOptions.port) {
+        logger.info(`Port ${effectiveOptions.port} already in use. Using next free port: ${port} for the AppRouter.`);
+    }
+    const subdomain = effectiveOptions.subdomain;
+    const baseUri = subdomain ? `http://${subdomain}.localhost:${port}` : `http://localhost:${port}`;
+    const callbackEndpoint = xsappConfig.login?.callbackEndpoint ?? '/login/callback';
+    const customRoutes = [...extensionsRoutes, callbackEndpoint];
+    if (!effectiveOptions.disableWelcomeFile) {
+        customRoutes.unshift('/');
+    }
+    const logoutEndpoint = xsappConfig.logout?.logoutEndpoint;
+    if (logoutEndpoint) {
+        customRoutes.push(logoutEndpoint);
+    }
+    const basUrlTemplate = await (0, bas_1.fetchBasUrlTemplate)(logger);
+    let initialized = false;
+    let proxyMiddleware = null;
+    return function lazyApprouterMiddleware(req, res, next) {
+        if (!initialized) {
+            try {
+                const actualPort = req.socket.localPort ?? 8080;
+                const basExternalUrl = (0, bas_1.resolveBasExternalUrl)(basUrlTemplate, actualPort);
+                if (basExternalUrl) {
+                    logger.info(`BAS detected. External URL: ${basExternalUrl.href}`);
+                }
+                if ((0, env_1.updateUi5ServerDestinationPort)(effectiveOptions, actualPort, basExternalUrl)) {
+                    logger.info(`Auto-configured ui5-server destination to port ${actualPort}`);
+                }
+                const routes = (0, routes_1.buildRouteEntries)({ xsappConfig, effectiveOptions, logger });
+                (0, approuter_1.startApprouter)({ port, xsappConfig, rootPath, modules, logger });
+                proxyMiddleware = (0, proxy_1.createProxy)({ customRoutes, routes, baseUri, effectiveOptions, basExternalUrl }, logger);
+                initialized = true;
+            }
+            catch (err) {
+                return next(err);
+            }
+        }
+        proxyMiddleware(req, res, next);
+    };
+}
+module.exports = backendProxyMiddlewareCf;
 //# sourceMappingURL=middleware.js.map

package/dist/platform/bas.d.ts

@@ -0,0 +1,19 @@
+import type { ToolsLogger } from '@sap-ux/logger';
+/**
+ * If running in BAS, fetch a URL template from the AppStudio API using a placeholder port.
+ * The template can later be resolved to the real port with {@link resolveBasExternalUrl}.
+ *
+ * @param logger - Logger instance.
+ * @returns URL template string, or empty string when not in BAS.
+ */
+export declare function fetchBasUrlTemplate(logger: ToolsLogger): Promise<string>;
+/**
+ * Replace the placeholder port in a BAS URL template with the actual runtime port
+ * and register the resulting hostname in `WS_ALLOWED_ORIGINS`.
+ *
+ * @param basUrlTemplate - Template URL from {@link fetchBasUrlTemplate}.
+ * @param actualPort - The real UI5 server port detected at runtime.
+ * @returns Resolved URL, or undefined if the template is empty.
+ */
+export declare function resolveBasExternalUrl(basUrlTemplate: string, actualPort: number): URL | undefined;
+//# sourceMappingURL=bas.d.ts.map

package/dist/platform/bas.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchBasUrlTemplate = fetchBasUrlTemplate;
+exports.resolveBasExternalUrl = resolveBasExternalUrl;
+const btp_utils_1 = require("@sap-ux/btp-utils");
+/** Port placeholder used to obtain a BAS URL template before the actual port is known. */
+const BAS_PORT_PLACEHOLDER = 0;
+/**
+ * If running in BAS, fetch a URL template from the AppStudio API using a placeholder port.
+ * The template can later be resolved to the real port with {@link resolveBasExternalUrl}.
+ *
+ * @param logger - Logger instance.
+ * @returns URL template string, or empty string when not in BAS.
+ */
+async function fetchBasUrlTemplate(logger) {
+    if (!(0, btp_utils_1.isAppStudio)()) {
+        return '';
+    }
+    return (0, btp_utils_1.exposePort)(BAS_PORT_PLACEHOLDER, logger);
+}
+/**
+ * Replace the placeholder port in a BAS URL template with the actual runtime port
+ * and register the resulting hostname in `WS_ALLOWED_ORIGINS`.
+ *
+ * @param basUrlTemplate - Template URL from {@link fetchBasUrlTemplate}.
+ * @param actualPort - The real UI5 server port detected at runtime.
+ * @returns Resolved URL, or undefined if the template is empty.
+ */
+function resolveBasExternalUrl(basUrlTemplate, actualPort) {
+    if (!basUrlTemplate) {
+        return undefined;
+    }
+    const basExternalUrl = new URL(basUrlTemplate.replace(`port${BAS_PORT_PLACEHOLDER}`, `port${actualPort}`));
+    const origins = JSON.parse(process.env.WS_ALLOWED_ORIGINS ?? '[]');
+    origins.push({ host: basExternalUrl.hostname });
+    process.env.WS_ALLOWED_ORIGINS = JSON.stringify(origins);
+    return basExternalUrl;
+}
+//# sourceMappingURL=bas.js.map

package/dist/platform/xssecurity.d.ts

@@ -0,0 +1,10 @@
+import type { ToolsLogger } from '@sap-ux/logger';
+/**
+ * Update the XSUAA service instance with oauth2-configuration redirect-uris
+ * so that OAuth redirects work correctly in the BAS environment.
+ *
+ * @param rootPath - Project root path (app folder; mta.yaml and xs-security.json are one level up).
+ * @param logger - Logger instance.
+ */
+export declare function updateXsuaaService(rootPath: string, logger: ToolsLogger): Promise<void>;
+//# sourceMappingURL=xssecurity.d.ts.map

package/dist/platform/xssecurity.js

@@ -0,0 +1,51 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateXsuaaService = updateXsuaaService;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const adp_tooling_1 = require("@sap-ux/adp-tooling");
+/**
+ * Update the XSUAA service instance with oauth2-configuration redirect-uris
+ * so that OAuth redirects work correctly in the BAS environment.
+ *
+ * @param rootPath - Project root path (app folder; mta.yaml and xs-security.json are one level up).
+ * @param logger - Logger instance.
+ */
+async function updateXsuaaService(rootPath, logger) {
+    try {
+        const projectRoot = node_path_1.default.resolve(rootPath, '..');
+        const xsSecurityPath = node_path_1.default.resolve(projectRoot, 'xs-security.json');
+        const mtaPath = node_path_1.default.resolve(projectRoot, 'mta.yaml');
+        if (!node_fs_1.default.existsSync(xsSecurityPath)) {
+            logger.warn(`xs-security.json not found at "${xsSecurityPath}", skipping XSUAA service update.`);
+            return;
+        }
+        if (!node_fs_1.default.existsSync(mtaPath)) {
+            logger.warn(`mta.yaml not found at "${mtaPath}", skipping XSUAA service update.`);
+            return;
+        }
+        const xsSecurityContent = JSON.parse(node_fs_1.default.readFileSync(xsSecurityPath, 'utf-8'));
+        const augmented = {
+            ...xsSecurityContent,
+            'oauth2-configuration': {
+                'redirect-uris': ['https://**.applicationstudio.cloud.sap/**', 'http://localhost:*/**']
+            }
+        };
+        const mtaServices = (0, adp_tooling_1.getServicesForFile)(mtaPath, logger);
+        const serviceInstanceName = mtaServices.find((s) => s.label === 'xsuaa')?.name;
+        if (!serviceInstanceName) {
+            logger.warn('No xsuaa service instance name found in mta.yaml, skipping XSUAA service update.');
+            return;
+        }
+        logger.info(`Updating XSUAA service instance "${serviceInstanceName}" with BAS redirect-uris.`);
+        await (0, adp_tooling_1.updateServiceInstance)(serviceInstanceName, augmented);
+        logger.info(`XSUAA service instance "${serviceInstanceName}" updated successfully.`);
+    }
+    catch (e) {
+        logger.error(`Failed to update XSUAA service instance for BAS: ${e.message}`);
+    }
+}
+//# sourceMappingURL=xssecurity.js.map

package/dist/proxy/proxy.d.ts

@@ -0,0 +1,22 @@
+import type { RequestHandler } from 'express';
+import { responseInterceptor } from 'http-proxy-middleware';
+import type { ToolsLogger } from '@sap-ux/logger';
+import type { CreateProxyOptions, EffectiveOptions, RouteEntry } from '../types';
+/**
+ * Create the response interceptor for the proxy (content-type + URL rewriting).
+ *
+ * @param routes - Route entries with regex and destination URLs.
+ * @param effectiveOptions - Merged options (rewriteContent, rewriteContentTypes, debug).
+ * @returns The interceptor function to pass to responseInterceptor().
+ */
+export declare function createResponseInterceptor(routes: RouteEntry[], effectiveOptions: EffectiveOptions): ReturnType<typeof responseInterceptor>;
+/**
+ * Create the proxy middleware that forwards matching requests to the approuter.
+ * Paths are proxied if they match any customRoute (e.g. welcome, login callback) or any destination route.
+ *
+ * @param options - customRoutes, routes, baseUri, effectiveOptions.
+ * @param logger - Logger instance.
+ * @returns Express request handler (the proxy middleware).
+ */
+export declare function createProxy(options: CreateProxyOptions, logger: ToolsLogger): RequestHandler;
+//# sourceMappingURL=proxy.d.ts.map

package/dist/proxy/proxy.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createResponseInterceptor = createResponseInterceptor;
+exports.createProxy = createProxy;
+const http_proxy_middleware_1 = require("http-proxy-middleware");
+const constants_1 = require("../config/constants");
+const utils_1 = require("./utils");
+/**
+ * Create the response interceptor for the proxy (content-type + URL rewriting).
+ *
+ * @param routes - Route entries with regex and destination URLs.
+ * @param effectiveOptions - Merged options (rewriteContent, rewriteContentTypes, debug).
+ * @returns The interceptor function to pass to responseInterceptor().
+ */
+function createResponseInterceptor(routes, effectiveOptions) {
+    return (0, http_proxy_middleware_1.responseInterceptor)(async (responseBuffer, proxyRes, req, res) => {
+        const url = req.url ?? '';
+        const pathname = /^[^?]*/.exec(url)?.[0] ?? url;
+        const { type, charset, contentType: ct } = (0, utils_1.getMimeInfo)(pathname, proxyRes.headers['content-type']);
+        res.setHeader('content-type', ct);
+        const route = routes.find((routeEntry) => routeEntry.sourcePattern.test(url));
+        if (route?.path && route.url && effectiveOptions?.rewriteContentTypes?.includes(type?.toLowerCase() ?? '')) {
+            const encoding = (charset ?? 'utf8');
+            let data = responseBuffer.toString(encoding);
+            const referrer = req.headers.referrer ?? req.headers.referer ?? (0, utils_1.getRequestOrigin)(req);
+            const referrerUrl = new URL(route.path, referrer).toString();
+            const routeUrlParsed = new URL(route.url);
+            const hostAndPath = `${routeUrlParsed.host}${routeUrlParsed.pathname}`;
+            data = (0, utils_1.replaceUrl)(data, `https://${hostAndPath}`, referrerUrl);
+            data = (0, utils_1.replaceUrl)(data, `http://${hostAndPath}`, referrerUrl);
+            return Buffer.from(data);
+        }
+        return responseBuffer;
+    });
+}
+/**
+ * Create the proxy middleware that forwards matching requests to the approuter.
+ * Paths are proxied if they match any customRoute (e.g. welcome, login callback) or any destination route.
+ *
+ * @param options - customRoutes, routes, baseUri, effectiveOptions.
+ * @param logger - Logger instance.
+ * @returns Express request handler (the proxy middleware).
+ */
+function createProxy(options, logger) {
+    const { customRoutes, routes, baseUri, effectiveOptions, basExternalUrl } = options;
+    const intercept = createResponseInterceptor(routes, effectiveOptions);
+    const proxyFilter = (0, utils_1.createProxyFilter)(customRoutes, routes);
+    const proxyMiddleware = (0, http_proxy_middleware_1.createProxyMiddleware)({
+        logger: effectiveOptions.debug ? logger : undefined,
+        target: baseUri,
+        pathFilter: proxyFilter,
+        changeOrigin: true,
+        selfHandleResponse: true,
+        autoRewrite: true,
+        xfwd: true,
+        on: {
+            proxyReq: (proxyReq, req, res) => {
+                proxyReq.setHeader(constants_1.PROXY_MARKER_HEADER, '1');
+                const xfp = req.headers['x-forwarded-proto'];
+                if (typeof xfp === 'string' && xfp.includes(',')) {
+                    const proto = xfp.split(',')[0];
+                    req.headers['x-forwarded-proto'] = proto;
+                    proxyReq.setHeader('x-forwarded-proto', proto);
+                }
+                if (basExternalUrl) {
+                    proxyReq.setHeader('x-forwarded-host', basExternalUrl.host);
+                    proxyReq.setHeader('x-forwarded-proto', basExternalUrl.protocol.replace(':', ''));
+                }
+                if (req['ui5-middleware-index']?.url === '/') {
+                    res['backend-proxy-middleware-cf'] = { redirected: true };
+                    const baseUrl = req['ui5-patched-router']?.baseUrl ?? '/';
+                    res.redirect(`${baseUrl === '/' ? '' : baseUrl}${req.url ?? ''}`);
+                }
+                else {
+                    const originalUrl = req['ui5-patched-router']?.originalUrl;
+                    if (originalUrl) {
+                        proxyReq.setHeader('x-forwarded-path', originalUrl);
+                    }
+                }
+            },
+            proxyRes: async (proxyRes, req, res) => {
+                if (!res['backend-proxy-middleware-cf']?.redirected) {
+                    return intercept(proxyRes, req, res);
+                }
+                return undefined;
+            },
+            error: (err, _req, res) => {
+                logger.error(`Approuter proxy error: ${err.message}`);
+                const response = res;
+                if (!response.headersSent) {
+                    response.writeHead(502, { 'Content-Type': 'text/plain' });
+                    response.end(`Approuter is not reachable: ${err.message}`);
+                }
+            }
+        }
+    });
+    return proxyMiddleware;
+}
+//# sourceMappingURL=proxy.js.map

package/dist/proxy/routes.d.ts

@@ -0,0 +1,18 @@
+import type { BuildRouteEntriesOptions, PrepareXsappConfigOptions, RouteEntry, XsappConfig } from '../types';
+/**
+ * Load xs-app.json and prepare it for the approuter (filter routes, set auth, optionally append auth route).
+ * Mutates and returns the config; does not build RouteEntry[].
+ *
+ * @param options - rootPath, xsappJsonPath, effectiveOptions, sourcePath.
+ * @returns The loaded and mutated XsappConfig.
+ */
+export declare function loadAndPrepareXsappConfig(options: PrepareXsappConfigOptions): XsappConfig;
+/**
+ * Build the list of route entries (compiled regex + resolved destination URLs) from a prepared xsappConfig.
+ * Does not read files or mutate xsappConfig.
+ *
+ * @param options - xsappConfig, effectiveOptions, logger.
+ * @returns Route entries for the proxy.
+ */
+export declare function buildRouteEntries(options: BuildRouteEntriesOptions): RouteEntry[];
+//# sourceMappingURL=routes.d.ts.map

package/dist/proxy/routes.js

@@ -0,0 +1,103 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAndPrepareXsappConfig = loadAndPrepareXsappConfig;
+exports.buildRouteEntries = buildRouteEntries;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const constants_1 = require("../config/constants");
+/**
+ * Auth route for HTML pages - triggers XSUAA login.
+ * Only this route is needed; /resources and /test-resources are handled
+ * directly by ui5-proxy-middleware without going through approuter.
+ */
+const UI5_SERVER_AUTH_ROUTE = {
+    source: String.raw `^/(test|local)/.*\.html.*$`,
+    destination: constants_1.UI5_SERVER_DESTINATION,
+    authenticationType: 'xsuaa'
+};
+/**
+ * Load xs-app.json and prepare it for the approuter (filter routes, set auth, optionally append auth route).
+ * Mutates and returns the config; does not build RouteEntry[].
+ *
+ * @param options - rootPath, xsappJsonPath, effectiveOptions, sourcePath.
+ * @returns The loaded and mutated XsappConfig.
+ */
+function loadAndPrepareXsappConfig(options) {
+    const { rootPath, xsappJsonPath, effectiveOptions, sourcePath, logger } = options;
+    const xsappConfig = JSON.parse(node_fs_1.default.readFileSync(xsappJsonPath, 'utf8'));
+    const xsappRoutes = xsappConfig.routes ?? [];
+    xsappConfig.routes = xsappRoutes.filter((route) => {
+        if (route.service === 'html5-apps-repo-rt') {
+            logger.debug(`Filtering out xs-app.json route: service "html5-apps-repo-rt" (source: ${route.source})`);
+            return false;
+        }
+        const hasResources = route.source.includes('/resources') || route.source.includes('/test-resources');
+        if (!route.localDir && route.authenticationType === 'none' && hasResources) {
+            logger.debug(`Filtering out xs-app.json route: unauthenticated resource route without localDir (source: ${route.source})`);
+            return false;
+        }
+        return true;
+    });
+    if (effectiveOptions.disableWelcomeFile) {
+        delete xsappConfig.welcomeFile;
+    }
+    xsappConfig.authenticationMethod = effectiveOptions.authenticationMethod;
+    if (effectiveOptions.appendAuthRoute &&
+        effectiveOptions.authenticationMethod &&
+        effectiveOptions.authenticationMethod !== 'none') {
+        const relativeSourcePath = node_path_1.default.relative(rootPath, sourcePath);
+        xsappConfig.routes.push({
+            source: String.raw `^/([^.]+\\.html?(?:\?.*)?)$`,
+            localDir: relativeSourcePath,
+            target: '$1',
+            cacheControl: 'no-store',
+            authenticationType: 'xsuaa'
+        });
+    }
+    if (xsappConfig.authenticationMethod?.toLowerCase() === 'none') {
+        for (const route of xsappConfig.routes) {
+            route.authenticationType = 'none';
+        }
+    }
+    if (!effectiveOptions.disableUi5ServerRoutes) {
+        // Inject only the HTML auth route - /resources and /test-resources
+        // are handled directly by ui5-proxy-middleware without approuter loop
+        xsappConfig.routes.push(UI5_SERVER_AUTH_ROUTE);
+    }
+    return xsappConfig;
+}
+/**
+ * Build the list of route entries (compiled regex + resolved destination URLs) from a prepared xsappConfig.
+ * Does not read files or mutate xsappConfig.
+ *
+ * @param options - xsappConfig, effectiveOptions, logger.
+ * @returns Route entries for the proxy.
+ */
+function buildRouteEntries(options) {
+    const { xsappConfig, effectiveOptions, logger } = options;
+    const routes = [];
+    const destList = Array.isArray(effectiveOptions.destinations) ? effectiveOptions.destinations : [];
+    for (const route of xsappConfig.routes ?? []) {
+        const routeMatch = /[^/]*\/(.*\/)?[^/]*/.exec(route.source);
+        if (!routeMatch) {
+            logger.warn(`Skipping route with source "${route.source}": could not extract path prefix.`);
+            continue;
+        }
+        const url = destList.find((d) => d.name === route.destination)?.url;
+        routes.push({
+            ...route,
+            sourcePattern: new RegExp(route.source),
+            path: routeMatch[1],
+            url
+        });
+        if (effectiveOptions.debug) {
+            const destination = route.destination ?? route.endpoint ?? '';
+            logger.debug(`Adding destination "${destination}" proxying to ${route.source}`);
+        }
+    }
+    return routes;
+}
+//# sourceMappingURL=routes.js.map