From a87bcfaf172625e23f9827c93d54e06899fbcee9 Mon Sep 17 00:00:00 2001 From: "Aaron K. Clark" Date: Tue, 19 May 2026 14:20:27 -0500 Subject: [PATCH] chore(server): document why crossOriginEmbedderPolicy is disabled MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The helmet config disables `crossOriginEmbedderPolicy` alongside the documented `contentSecurityPolicy: false`, but the COEP=false line had no comment explaining why. A future contributor reading the block could either assume it was an oversight (and try to re-enable it) or copy the pattern into a different app without understanding the constraint. Add the rationale: Swagger UI at /docs loads theme assets cross-origin, and helmet's default `require-corp` value blocks any sub-resource that doesn't explicitly opt into CORP/CORS. Since this API has no other browser-facing HTML, leaving COEP off is the lower-risk choice; operators adding embedded dashboards should configure helmet directly rather than re-enabling COEP at this layer. Comment-only — no behavior change, tests stay green. Co-Authored-By: Claude Opus 4.7 (1M context) --- server.js | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/server.js b/server.js index 909fe0f..a2eaa40 100644 --- a/server.js +++ b/server.js @@ -109,6 +109,16 @@ if (trustProxy === 'true') { // legitimate clients hitting the docs endpoint or future // browser-based dashboards. Operators who add an HTML surface // can re-enable via HELMET_CSP=1. +// +// crossOriginEmbedderPolicy is also disabled: Swagger UI at /docs +// loads its JS/CSS bundle from the package's own host but pulls +// theme assets cross-origin, and helmet's default +// `require-corp` value blocks any sub-resource that doesn't +// explicitly opt into CORP/CORS — which would break the docs +// page on first load. Since this API has no other browser-facing +// HTML, leaving COEP off is the lower-risk choice. Operators +// hosting embedded dashboards alongside the API should configure +// helmet directly rather than re-enabling COEP at this layer. app.use(helmet({ contentSecurityPolicy: process.env.HELMET_CSP === '1' ? undefined : false, crossOriginEmbedderPolicy: false,