@botfabrik/engine-webclient 4.109.12-alpha.2 → 4.109.12-alpha.4

package/dist/applySecurityMiddleware.d.ts

@@ -0,0 +1,10 @@
+import type { Router } from 'express';
+import type { WebClientProps } from './types.js';
+/**
+ * Applies CORS, Helmet (CSP) and Permissions-Policy middleware to the given router.
+ *
+ * @param router - The Express router to apply middleware to.
+ * @param props - The webclient configuration.
+ * @param baseUrl - The server's own base URL (e.g. "http://localhost:3000").
+ */
+export declare function applySecurityMiddleware(router: Router, props: WebClientProps, baseUrl: string): void;

package/dist/applySecurityMiddleware.js

@@ -0,0 +1,116 @@
+import cors from 'cors';
+import helmet from 'helmet';
+/**
+ * Applies CORS, Helmet (CSP) and Permissions-Policy middleware to the given router.
+ *
+ * @param router - The Express router to apply middleware to.
+ * @param props - The webclient configuration.
+ * @param baseUrl - The server's own base URL (e.g. "http://localhost:3000").
+ */
+export function applySecurityMiddleware(router, props, baseUrl) {
+    const { allowedOrigins, trustedResourceOrigins } = props;
+    // CORS
+    // When allowedOrigins is undefined, all origins are permitted (backward-compatible default).
+    // When it is set (even to an empty array), only the listed origins plus the server's own
+    // base URL are allowed.
+    router.use(cors({
+        origin: allowedOrigins === undefined
+            ? true
+            : (origin, callback) => {
+                // The server's own origin is always allowed.
+                const effectiveAllowed = [baseUrl, ...allowedOrigins];
+                if (!origin || effectiveAllowed.includes(origin)) {
+                    callback(null, true);
+                }
+                else {
+                    callback(new Error(`CORS: Origin '${origin}' is not allowed`));
+                }
+            },
+        methods: ['GET', 'POST', 'OPTIONS'],
+        allowedHeaders: ['Content-Type', 'Authorization'],
+        credentials: true,
+    }));
+    // Helmet (CSP + security headers)
+    router.use(helmet({
+        contentSecurityPolicy: {
+            directives: {
+                defaultSrc: ["'self'"],
+                scriptSrc: ["'self'"],
+                // stylesheets: allow all HTTPS sources when no trustedResourceOrigins are configured
+                // (backward-compatible default); otherwise restrict to the listed origins
+                styleSrc: trustedResourceOrigins === undefined
+                    ? ["'self'", "'unsafe-inline'", 'https:']
+                    : ["'self'", "'unsafe-inline'", ...trustedResourceOrigins],
+                // images: restrict to trusted resource origins when defined, otherwise allow all HTTPS
+                imgSrc: trustedResourceOrigins === undefined
+                    ? ["'self'", 'data:', 'https:']
+                    : ["'self'", 'data:', ...trustedResourceOrigins],
+                connectSrc: [
+                    "'self'",
+                    // allow websocket connections back to the same server
+                    baseUrl.replace(/^http/, 'ws'),
+                    baseUrl.replace(/^http/, 'wss'),
+                ],
+                // fonts may be loaded from trusted resource origins (e.g. Google Fonts);
+                // when no trustedResourceOrigins are configured, allow fonts from all origins
+                fontSrc: trustedResourceOrigins === undefined
+                    ? ['*']
+                    : ["'self'", ...trustedResourceOrigins],
+                // when no allowedOrigins are configured, allow framing from all origins
+                frameAncestors: allowedOrigins === undefined
+                    ? ['*']
+                    : ["'self'", ...allowedOrigins],
+                // frame-src controls what this page may embed in an iframe.
+                // The /embed page loads the chatbot in an iframe on the same server.
+                // We include both http and https of the server's base URL because a browser
+                // with a cached HSTS policy for localhost may load the iframe via https://
+                // even when the embed page was served via http://.
+                frameSrc: [
+                    "'self'",
+                    baseUrl,
+                    baseUrl.replace(/^http:/, 'https:'),
+                    ...(allowedOrigins ?? []),
+                ],
+                objectSrc: ["'none'"],
+                baseUri: ["'self'"],
+                // When SAML auth is configured, the browser POSTs a form to the external IdP.
+                formAction: props.auth?.saml.entryPoint
+                    ? ["'self'", props.auth.saml.entryPoint]
+                    : ["'self'"],
+                // upgrade-insecure-requests is intentionally omitted:
+                // the webclient is embedded via iframe on external pages which may themselves be HTTP,
+                // and the directive would also affect those sub-resource loads in some browsers.
+                // Helmet adds upgrade-insecure-requests by default; we must explicitly disable it
+                // here because it would also upgrade HTTP redirects (e.g. bot.svg → /cms/...) to HTTPS,
+                // causing ERR_SSL_PROTOCOL_ERROR in local development.
+                upgradeInsecureRequests: null,
+            },
+        },
+        // Disable X-Frame-Options: we control framing exclusively via CSP frame-ancestors above.
+        // X-Frame-Options: SAMEORIGIN (helmet default) would block cross-origin iframe embedding.
+        frameguard: false,
+        // Send origin only, without path – sufficient for analytics while avoiding leaking URLs
+        referrerPolicy: { policy: 'strict-origin-when-cross-origin' },
+        // Disable HSTS: HTTPS enforcement is already handled globally in engine-core.
+        // Enabling it here would cause the browser to enforce HTTPS for the entire origin,
+        // which breaks local development (http://localhost:3000).
+        hsts: false,
+        // resources served by the webclient must be loadable cross-origin (e.g. embed script)
+        crossOriginResourcePolicy: { policy: 'cross-origin' },
+    }));
+    // Permissions-Policy: restrict browser feature access to the minimum required.
+    // Microphone is only permitted when speech-to-text is configured.
+    router.use((_req, res, next) => {
+        const microphonePolicy = props.speech
+            ? 'microphone=(self)'
+            : 'microphone=()';
+        res.setHeader('Permissions-Policy', [
+            microphonePolicy,
+            'camera=()',
+            'geolocation=()',
+            'payment=()',
+            'usb=()',
+        ].join(', '));
+        next();
+    });
+}

package/dist/applySecurityMiddleware.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/applySecurityMiddleware.test.js

@@ -0,0 +1,99 @@
+import express from 'express';
+import supertest from 'supertest';
+import { describe, expect, it } from 'vitest';
+import { applySecurityMiddleware } from './applySecurityMiddleware.js';
+const BASE_URL = 'http://localhost:3000';
+describe('security middleware', () => {
+    describe('CORS', () => {
+        it('allows all origins when allowedOrigins is undefined', async () => {
+            const res = await supertest(makeApp({}))
+                .get('/')
+                .set('Origin', 'http://any-origin.example.com');
+            expect(res.headers['access-control-allow-origin']).toBe('http://any-origin.example.com');
+        });
+        it('allows the server baseUrl when allowedOrigins is []', async () => {
+            const res = await supertest(makeApp({ allowedOrigins: [] }))
+                .get('/')
+                .set('Origin', BASE_URL);
+            expect(res.headers['access-control-allow-origin']).toBe(BASE_URL);
+        });
+        it('allows an explicitly listed origin', async () => {
+            const res = await supertest(makeApp({ allowedOrigins: ['http://example.com'] }))
+                .get('/')
+                .set('Origin', 'http://example.com');
+            expect(res.headers['access-control-allow-origin']).toBe('http://example.com');
+        });
+        it('rejects an unlisted origin', async () => {
+            const res = await supertest(makeApp({ allowedOrigins: ['http://example.com'] }))
+                .get('/')
+                .set('Origin', 'http://evil.example.com');
+            // cors package sets the header to false/omits it when rejected
+            expect(res.headers['access-control-allow-origin']).toBeUndefined();
+        });
+        it('allows no-origin requests (same-origin non-browser) regardless of allowedOrigins', async () => {
+            const res = await supertest(makeApp({ allowedOrigins: [] })).get('/');
+            expect(res.status).toBe(200);
+        });
+    });
+    describe('CSP frame-ancestors', () => {
+        it("is '*' when allowedOrigins is undefined", async () => {
+            const res = await supertest(makeApp({})).get('/');
+            expect(res.headers['content-security-policy']).toContain('frame-ancestors *');
+        });
+        it('is "\'self\'" + listed origin when allowedOrigins is set', async () => {
+            const res = await supertest(makeApp({ allowedOrigins: ['http://example.com'] })).get('/');
+            expect(res.headers['content-security-policy']).toContain("frame-ancestors 'self' http://example.com");
+        });
+        it('is "\'self\'" only when allowedOrigins is []', async () => {
+            const res = await supertest(makeApp({ allowedOrigins: [] })).get('/');
+            expect(res.headers['content-security-policy']).toContain("frame-ancestors 'self'");
+        });
+    });
+    describe('CSP connectSrc', () => {
+        it('includes ws:// and wss:// variants of baseUrl', async () => {
+            const res = await supertest(makeApp({}, 'http://bot.example.com')).get('/');
+            const csp = res.headers['content-security-policy'];
+            expect(csp).toContain('ws://bot.example.com');
+            expect(csp).toContain('wss://bot.example.com');
+        });
+    });
+    describe('CSP trustedResourceOrigins', () => {
+        it('allows all HTTPS for styleSrc/imgSrc/fontSrc when undefined', async () => {
+            const res = await supertest(makeApp({})).get('/');
+            const csp = res.headers['content-security-policy'];
+            expect(csp).toContain('style-src');
+            expect(csp).toContain('https:');
+            expect(csp).toContain('font-src *');
+        });
+        it('restricts styleSrc/imgSrc/fontSrc to listed origins when set', async () => {
+            const res = await supertest(makeApp({ trustedResourceOrigins: ['https://fonts.googleapis.com'] })).get('/');
+            const csp = res.headers['content-security-policy'];
+            expect(csp).toContain('https://fonts.googleapis.com');
+            expect(csp).not.toContain('font-src *');
+        });
+    });
+    describe('Permissions-Policy', () => {
+        it('disables microphone when no speech config', async () => {
+            const res = await supertest(makeApp({})).get('/');
+            expect(res.headers['permissions-policy']).toContain('microphone=()');
+        });
+        it('allows microphone when speech is configured', async () => {
+            const res = await supertest(makeApp({ speech: { provider: 'google' } })).get('/');
+            expect(res.headers['permissions-policy']).toContain('microphone=(self)');
+        });
+        it('always disables camera, geolocation, payment and usb', async () => {
+            const res = await supertest(makeApp({})).get('/');
+            const pp = res.headers['permissions-policy'];
+            expect(pp).toContain('camera=()');
+            expect(pp).toContain('geolocation=()');
+            expect(pp).toContain('payment=()');
+            expect(pp).toContain('usb=()');
+        });
+    });
+});
+function makeApp(props, baseUrl = BASE_URL) {
+    const app = express();
+    applySecurityMiddleware(app, props, baseUrl);
+    app.get('/', (_req, res) => res.json({ ok: true }));
+    return app;
+}