gina 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -6,6 +6,16 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.4.7 - 2026-06-11
+### Added
+* Csp plugin: new opt-in reportOnlyOmit option — an array of directive names to omit from a Content-Security-Policy-Report-Only header and emit again automatically when reportOnly flips to false, so one directive set covers both modes. Built for engine-divergent directives such as frame-ancestors (reported in report-only by Chrome and Firefox, ignored with a console warning by Safari/WebKit): a bundle can trade the Gecko/Blink report signal for a clean WebKit console as an explicit, lifecycle-managed choice. Entries are validated against the CSP Level 3 whitelist, a factory-time warning names what was dropped, and the default output is unchanged.
+* HTTP/2 server (Isaac engine): opt-in RFC 8441 extended CONNECT enablement via the new settings.json http2Options.enableConnectProtocol flag (strict boolean, default false). When enabled on an http/2 bundle (https or cleartext h2c), the server advertises SETTINGS_ENABLE_CONNECT_PROTOCOL and handles extended CONNECT streams — the WebSocket-over-HTTP/2 handshake transport — with clean HTTP-status refusals as groundwork for the upcoming WebSocket session bridge: plain CONNECT keeps its 405, non-websocket :protocol values and not-yet-consumed websocket streams get 501, and an HTTP/1.1 CONNECT arriving over the allowHTTP1 fallback is refused with a raw 405 instead of an unanswered connection drop. A new extendedConnect counter joins the http2 metrics block in /_gina/info. Deployments that leave the flag off are byte-identical to previous releases.
+* New lib/ws-framing framework library: a dependency-free RFC 6455 WebSocket framing codec — frame encoder (minimal length encoding across the 7/16/64-bit forms, control-frame constraints, optional masking) and incremental per-connection parser (fragmentation reassembly, client-masking enforcement, UTF-8 validation of text payloads and close reasons, close-status-code validation, and DoS caps maxPayload/maxFragments enforced from declared frame lengths before any payload is buffered). Registered on the lib registry as wsFraming; transport-agnostic groundwork for WebSocket over HTTP/2 (RFC 8441 extended CONNECT).
+* WebSocket over HTTP/2 (RFC 8441): bundles can now serve WebSocket endpoints over the extended-CONNECT transport. From onInitialize, app.onWebSocket(path, handler) registers a handler per exact pathname; matched streams are answered with :status 200 and handed to the handler as a lib/ws-session session — send/ping/close API with automatic pong replies, a timed close handshake, backpressure passthrough, full teardown on stream close/error, contained consumer-handler exceptions (a throwing handler closes the session with 1011 instead of crashing the bundle), and graceful SIGTERM drain (live sessions are closed with 1001 going away instead of blocking shutdown). Requires an http/2 bundle (https or cleartext h2c) with http2Options.enableConnectProtocol set to true; unknown pathnames are refused with 404, registrations on a non-HTTP/2 bundle warn instead of crashing, and no express middleware runs on the CONNECT path — authentication is the handler's responsibility from the request it receives.
+### Fixed
+* HTTP/2 server (Isaac engine): cleartext h2c bundles now receive the same hardening options as https bundles — the SETTINGS advert (maxConcurrentStreams, initialWindowSize, maxHeaderListSize, enablePush off) and the session flood caps (maxSessionRejectedStreams, maxSessionInvalidFrames) are passed to http2.createServer instead of a bare allowHTTP1 literal. Previously an h2c bundle (e.g. behind a TLS-terminating reverse proxy) advertised protocol defaults — effectively unlimited concurrent streams with server push enabled — and silently ignored its settings.json http2Options overrides. The RFC 8441 enableConnectProtocol opt-in (WebSocket over HTTP/2) now applies to h2c bundles as well; it remains a strict opt-in defaulting to false.
+* Graceful shutdown: bundles with live WebSocket or engine.io connections no longer block SIGTERM shutdown until the hard timeout — every accepted engine.io socket and every /_gina/agent Inspector WebSocket now registers a per-socket closer in the framework shutdown drain (the same registry the Inspector SSE endpoints and WebSocket-over-HTTP/2 sessions already use), so shutdown closes them before the HTTP server close: engine.io sockets get a graceful transport close, agent WebSockets a clean 1001 going-away close handshake.
+
 ## 0.4.6 - 2026-06-10
 ### Added
 * Added an opt-in async template-loader extension point for the swig engine (settings.template.swig.loader): render templates from a custom backend instead of the local filesystem through an isolated per-bundle engine, with a built-in in-memory loader and a CVE-2023-25345 path-traversal guard. Remote/object-storage loaders and full asset-injection parity land in follow-ups.

package/README.md

@@ -39,14 +39,12 @@ gina bundle:start api @myproject
 open https://localhost:3100
 ```
 
-## What's in 0.4.6
-
-- **Async template loaders (opt-in).** `settings.template.swig.loader` / `settings.template.nunjucks.loader` render templates from a custom backend instead of the local filesystem — built-in `memory` and `http` loaders (for templates served from a CDN, object storage or a template service), per-bundle isolated engines, full client-runtime injection on the async path, and an opt-in compiled-template cache (`loader.cache`) for production.
-- **Native dialog API.** `data-gina-dialog="ID"` opens an in-page `<dialog>`, `data-gina-dialog-src="URL"` loads its content over AJAX; non-modal by default, with per-trigger (`data-gina-dialog-modal`) or project-wide modal opt-in. Dialog popins now render as native modals in development too (dev/prod parity), and the popin plugin gains an opt-in `preOpen` loading skeleton.
-- **`request.rawBody`.** The exact unparsed request body is preserved before parsing, so controllers and middlewares can verify inbound webhook signatures (an HMAC computed over the raw bytes).
-- **JSON bodies parsed verbatim.** `application/json` POST / PUT / PATCH bodies are no longer URL-decoded and form-coerced — string values such as `"true"` or `"50%20off"` survive exactly as sent. Urlencoded handling is unchanged, and the browser form-validator now sends its JSON bodies with the matching `application/json` Content-Type.
-- **Hardening.** A single request carrying a malformed percent-escape (a bare `%`, `%zz`) can no longer crash a bundle; the default Swig render path keeps the swig-core CVE-2023-25345 path-traversal confinement active; the `@rhinostone/swig` floor moved to `^2.7.2`; and the dead third-party CORS proxy was removed from the popin and link loaders.
-- **CLI & DX.** `gina version` reports the bundled template engine; offline project commands skip a stale registered project instead of aborting; `project:add` and the framework's self-invocations no longer depend on a PATH-resolved gina binary.
+## What's in 0.4.7
+
+- **WebSocket over HTTP/2 (opt-in).** HTTP/2 bundles can serve WebSocket endpoints over the RFC 8441 extended-CONNECT transport, with a built-in dependency-free RFC 6455 framing codec — no external WebSocket library. Enable with `http2Options.enableConnectProtocol: true`, then register handlers from `onInitialize` with `app.onWebSocket(path, handler)`: each accepted stream arrives as a session with a `send`/`ping`/`close` API, automatic pong replies, payload and fragment caps, and a graceful close handshake.
+- **HTTP/2 hardening parity for h2c.** Cleartext HTTP/2 bundles (for example, backends behind a TLS-terminating reverse proxy) now receive the same hardening as `https` bundles — the stream caps, session flood defenses, and `settings.json` `http2Options` overrides all apply, where previously such bundles ran protocol defaults (effectively unlimited concurrent streams with server push enabled) and silently ignored their overrides.
+- **Graceful shutdown for live sockets.** Bundles with open WebSocket or engine.io connections no longer block SIGTERM shutdown until the hard timeout — every live socket is closed cleanly before the HTTP server closes, WebSockets with a `1001 going away` close handshake.
+- **CSP `reportOnlyOmit` (opt-in).** Omit engine-divergent directives such as `frame-ancestors` from `Content-Security-Policy-Report-Only` headers and have them restored automatically when `reportOnly` flips to `false` — one directive set across both modes, validated against the CSP Level 3 whitelist.
 
 See the full [Changelog](./CHANGELOG.md) and [Roadmap](./ROADMAP.md).
 

package/ROADMAP.md

@@ -285,9 +285,9 @@ A cold audit of the Couchbase connector identified two critical security vulnera
 | ✅ | **Configurable `maxConcurrentStreams` and `initialWindowSize`** — move from hardcoded to `settings.json` `http2Options` | `0.3.0-alpha.1` | 2026-04-05 | All four HTTP/2 server settings configurable: `maxConcurrentStreams` (256), `initialWindowSize` (655350), `maxSessionRejectedStreams` (100), `maxSessionInvalidFrames` (1000). Security guards (`maxHeaderListSize`, `enablePush`) remain hardcoded. |
 | ✅ | **Application-level rapid reset rate limiter** (CVE-2023-44487) — per-session stream creation counter | `0.3.13` | 2026-05-14 | The Isaac HTTP/2 session handler counts new streams in a rolling 1s window per session; over `maxStreamsPerSecond` (default 200) it sends a GOAWAY and closes the session. More targeted than `maxSessionRejectedStreams` (which counts refused streams, not created ones). Configurable via `settings.json` `http2Options.maxStreamsPerSecond`; `/_gina/info` exposes a `rapidResetBlocked` counter. |
 | ✅ | **Trailer support** — `stream.sendTrailers()` + `waitForTrailers: true` | `0.4.0` | 2026-05-22 | Opt-in HTTP/2 response trailers via `self.sendTrailers(fields)`. The render pipeline sets `waitForTrailers` and emits the trailing headers after the body (in the `wantTrailers` event), across all render delegates. Activated only when a controller calls `self.sendTrailers(fields)`; HTTP/1.1 and the no-trailers path are unchanged. For gRPC-style streaming (`grpc-status`) and content-integrity (`Digest`) use cases. |
-| ✅ | **Alt-Svc header** — advertise HTTP/3 availability | `0.5.0` | Q1 2027 | Set `Alt-Svc: h3=":443"; ma=86400` response header to advertise HTTP/3 (QUIC) availability via a QUIC-capable reverse proxy (nginx, Caddy, Cloudflare). Gina does not need to implement QUIC — just announce it. Opt-in via `settings.server.json`. Native HTTP/3 is out of scope: Node.js has no stable QUIC API, and the standard deployment topology (Gina → proxy → client) already delivers HTTP/3 at the edge. |
+| ✅ | **Alt-Svc header** — advertise HTTP/3 availability | `0.4.2` | 2026-06-02 | Set `Alt-Svc: h3=":443"; ma=86400` response header to advertise HTTP/3 (QUIC) availability via a QUIC-capable reverse proxy (nginx, Caddy, Cloudflare). Gina does not need to implement QUIC — just announce it. Opt-in via `settings.server.json`. Native HTTP/3 is out of scope: Node.js has no stable QUIC API, and the standard deployment topology (Gina → proxy → client) already delivers HTTP/3 at the edge. |
 | 📋 | **RFC 9218 Extensible Priorities** — read `Priority: u=N, i` request header | `0.5.0` | Q1 2027 | Use the RFC 9218 priority header to order response writes for multiplexed API clients. Low value for typical HTML page loads; high value for parallel API requests with declared urgency. |
-| 📋 | **WebSocket over HTTP/2** (RFC 8441 — CONNECT method extension) | `0.5.0` | Q1 2027 | Tunnel WebSocket over an HTTP/2 stream without a separate HTTP/1.1 connection. Node.js supports this since v10.19. Enables WebSocket in HTTP/2-only deployments. |
+| ✅ | **WebSocket over HTTP/2** (RFC 8441 extended CONNECT) — opt-in via `http2Options.enableConnectProtocol` (default off; https and cleartext h2c HTTP/2 bundles). From `onInitialize`, `app.onWebSocket(path, handler)` registers per-path WebSocket handlers; accepted streams arrive as full sessions backed by a built-in dependency-free RFC 6455 codec (auto-pong, timed close handshake, UTF-8 + close-code validation, payload/fragment DoS caps, backpressure passthrough, graceful shutdown drain). Unknown paths are refused with 404, plain CONNECT keeps its 405, and default-off deployments are byte-identical. | `0.4.7` | 2026-06-11 |
 
 ---
 

package/framework/v0.4.7/VERSION

@@ -0,0 +1 @@
+0.4.7

package/framework/{v0.4.6 → v0.4.7}/core/plugins/lib/security-headers/csp/README.md

@@ -68,6 +68,8 @@ Settings.json shape — caller-supplied options always win over settings:
 |--------------|---------|---------|----------------------------------------------------------------------|
 | `directives` | object  | —       | **Required.** Throws if missing or empty. See "Directives" below.   |
 | `reportOnly` | boolean | `false` | When `true`, emits `Content-Security-Policy-Report-Only` instead.   |
+| `reportOnlyOmit` | string[] | `[]` | Directives to *also* omit while `reportOnly` is `true`; emitted again automatically in enforce mode. See "reportOnlyOmit" below. |
+| `useNonce`   | boolean | `false` | When `true`, generates a per-response nonce, stamps it on `req._ginaCspNonce`, and appends `'nonce-XXXX'` to `script-src` (fallback `default-src`). See "Per-response CSP nonce" below. |
 
 There is no sensible cross-bundle default for `directives`. Every bundle
 has its own resource graph; a default policy would either be too restrictive
@@ -177,8 +179,9 @@ CSP Level 2 rule — *"The frame-ancestors directive MUST be ignored when
 monitoring a policy"* — which CSP Level 3 dropped; CSP3 only restricts `<meta>`
 delivery, which a report-only policy never uses). The plugin keeps it so the
 observation phase still reports on Chrome and Firefox. If you serve a
-WebKit-heavy audience and want a clean Safari console, leave `frame-ancestors`
-out of your report-only directive set — clickjacking protection stays enforced
+WebKit-heavy audience and want a clean Safari console, opt it out with
+`reportOnlyOmit: ['frame-ancestors']` (next section) — clickjacking protection
+stays enforced
 by `X-Frame-Options` and/or an enforcing-mode `frame-ancestors`. (Chrome caveat:
 frame-ancestors violation reports are delivered via `report-uri`; known Chromium
 bugs leave them undelivered via `report-to`.) A report-only policy whose every
@@ -188,6 +191,54 @@ time**, since it would report nothing.
 The omitted set is intentionally conservative — `sandbox` is the only directive
 confirmed ignored in report-only across all engines.
 
+### `reportOnlyOmit` — opt out engine-divergent directives in report-only
+
+For the engine-divergent case above, `reportOnlyOmit` packages the
+hand-managed omission: every directive named in it is omitted from the
+report-only header and emitted again **automatically** when `reportOnly`
+flips to `false` — one directive set across both modes, no
+remove-then-re-add churn.
+
+```js
+require('gina').plugins.Csp({
+    reportOnly: true,
+    directives: {
+        'script-src':      ["'self'"],
+        'frame-ancestors': ["'self'"],
+        'report-uri':      ['/csp/report']
+    },
+    reportOnlyOmit: ['frame-ancestors']
+});
+// report-only header:  script-src 'self'; report-uri /csp/report
+// after the enforce flip (reportOnly: false): frame-ancestors 'self' returns
+```
+
+**The honest trade — the option packages the engine divergence, it does not
+eliminate it.** Listing `frame-ancestors` in `reportOnlyOmit` forgoes its
+Chrome + Firefox (Gecko + Blink) report-only monitoring signal in exchange
+for a clean WebKit console. The header is engine-blind, so gina cannot do
+better — the option just turns the hand-managed comment into an explicit,
+per-bundle, lifecycle-managed choice. Clickjacking stays enforced by
+`X-Frame-Options` and/or an enforcing-mode `frame-ancestors` regardless.
+
+Mechanics:
+
+- Entries are validated against the same CSP Level 3 whitelist as
+  `directives` keys — unknown names throw at factory call time.
+- A factory-time warning names what was dropped, with wording distinct from
+  the browser-inert `sandbox` omission — these directives are *not* ignored
+  by browsers; you are choosing to forgo their report signal.
+- An entry not present in `directives` warns in report-only mode (likely a
+  config mistake) and no-ops.
+- With `reportOnly: false` the option is inert **and silent** — keeping it
+  in an enforce-mode config is the expected lifecycle state, not a mistake.
+- If the omissions empty the report-only directive set, the factory throws
+  (same as the all-inert case).
+- `useNonce: true` with the nonce-target directive (`script-src` /
+  `default-src`) in `reportOnlyOmit` throws at factory call time — the
+  nonce would be stamped on the request and the tags but never referenced
+  by the emitted policy.
+
 ## Per-response CSP nonce (`useNonce`)
 
 Set `useNonce: true` to drop `'unsafe-inline'` from `script-src` without
@@ -252,6 +303,10 @@ console at runtime. Gina favours fail-fast.
 | All directives resolve to `false` (omitted)              | Factory throws — empty CSP is invalid                |
 | `reportOnly` is non-boolean                              | Factory throws                                       |
 | `reportOnly:true` with only report-only-inert directives | Factory throws — a report-only policy would report nothing |
+| `reportOnlyOmit` is non-array / has non-string entries   | Factory throws                                       |
+| `reportOnlyOmit` contains an unknown directive name      | Factory throws with full whitelist in message        |
+| `reportOnlyOmit` empties the report-only directive set   | Factory throws — the policy would report nothing     |
+| `reportOnlyOmit` omits the nonce target while `useNonce:true` | Factory throws — the header would never reference the nonce |
 | Plugin not registered                                    | Header not emitted; browser applies no CSP           |
 | Header already set by an earlier middleware              | Existing value preserved (idempotent)                |
 | Response already sent (`res.headersSent === true`)       | Node's `setHeader` no-ops; request resumes           |

package/framework/{v0.4.6 → v0.4.7}/core/plugins/lib/security-headers/csp/src/main.js

@@ -92,9 +92,30 @@
  * a console warning and no report (it retains CSP2's rule that the directive
  * MUST be ignored when monitoring, which CSP3 dropped). Keeping it preserves
  * the observation-phase signal on Chrome + Firefox; WebKit-heavy consumers
- * can leave it out of their own report-only directive set. A report-only
- * policy whose every directive is inert (e.g. only `sandbox`) throws at
- * factory call time.
+ * can opt it out via `reportOnlyOmit` (below). A report-only policy whose
+ * every directive is inert (e.g. only `sandbox`) throws at factory call
+ * time.
+ *
+ * **`reportOnlyOmit: ['frame-ancestors']`** (opt-in, default `[]`) extends
+ * the report-only omission to consumer-chosen directives: every directive
+ * named is omitted from the report-only header and emitted again
+ * automatically when `reportOnly` flips to `false` — one directive set
+ * across both modes, no remove-then-re-add churn. Built for the
+ * engine-divergent case above: a consumer serving WebKit-heavy audiences can
+ * drop `frame-ancestors` for a clean Safari console, explicitly trading away
+ * the Chrome + Firefox report-only signal (the header is engine-blind; the
+ * option just makes that trade an explicit, lifecycle-managed choice). The
+ * factory-time `console.warn` for these uses wording distinct from the
+ * browser-inert omission above — they are NOT ignored by browsers. Entries
+ * are validated against the same CSP Level 3 whitelist as `directives` keys
+ * (unknown names throw); an entry not present in `directives` warns in
+ * report-only mode (likely a config mistake) and no-ops; with
+ * `reportOnly: false` the option is inert and silent — an enforce-mode
+ * config is EXPECTED to keep carrying it.
+ * `useNonce: true` with the nonce-target directive (script-src /
+ * default-src) in `reportOnlyOmit` throws at factory call time — the nonce
+ * would be stamped on the request and the tags but never referenced by the
+ * emitted policy.
  *
  * Opens Phase 2 of the gina security-headers track (Phase 1 = HDR1-4 +
  * HDR7 shipped in 0.3.15-alpha). Single-header plugin shape — composes
@@ -208,9 +229,10 @@ var HYBRID_DIRECTIVES = [
  *    delivery, which a report-only policy cannot use anyway). Omitting it
  *    would discard the observation-phase signal on Chrome + Firefox;
  *    consumers serving WebKit-heavy audiences that want a clean Safari
- *    console can omit it from their own report-only directive set
- *    (clickjacking stays enforced by X-Frame-Options and/or an enforcing
- *    frame-ancestors regardless).
+ *    console can opt it out per-config via `reportOnlyOmit:
+ *    ['frame-ancestors']` — omitted in report-only, auto-restored in
+ *    enforce mode (clickjacking stays enforced by X-Frame-Options and/or an
+ *    enforcing frame-ancestors regardless).
  *  - `upgrade-insecure-requests` / `block-all-mixed-content` — not confirmed
  *    inert across engines: Chromium ignores-and-warns
  *    `upgrade-insecure-requests` in report-only but supports
@@ -442,6 +464,59 @@ function resolveReportOnly(value) {
 }
 
 
+/**
+ * Validate and normalise the `reportOnlyOmit` option — consumer-chosen
+ * directives to ALSO omit from a report-only header, on top of the
+ * universally-inert `REPORT_ONLY_IGNORED_DIRECTIVES`. Defaults to `[]`.
+ *
+ * Entries are lowercased and validated against the same CSP Level 3
+ * whitelist as `directives` keys; duplicates are dropped. Only consulted
+ * when `reportOnly` is true (inert and silent otherwise — keeping it in an
+ * enforce-mode config is the expected lifecycle state, not a mistake), but
+ * validated unconditionally so a malformed entry fails at boot rather than
+ * surfacing on the next `reportOnly` flip.
+ *
+ * @param {*} value
+ * @returns {string[]} normalised, deduplicated directive names.
+ * @throws  {Error} on non-array shapes, non-string entries, unknown names.
+ * @inner
+ * @private
+ */
+function resolveReportOnlyOmit(value) {
+    if (typeof value === 'undefined' || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(
+            '[gina.plugins.Csp] reportOnlyOmit must be an array of CSP directive '
+            + 'names to omit from a report-only header (e.g. ["frame-ancestors"]); '
+            + 'received ' + typeof value + '.'
+        );
+    }
+    var out = [];
+    for (var i = 0; i < value.length; i++) {
+        if (typeof value[i] !== 'string') {
+            throw new Error(
+                '[gina.plugins.Csp] reportOnlyOmit entries must be strings; '
+                + 'received ' + typeof value[i] + ' at index ' + i + '.'
+            );
+        }
+        var name = String(value[i]).toLowerCase();
+        if (VALID_DIRECTIVES.indexOf(name) === -1) {
+            throw new Error(
+                '[gina.plugins.Csp] unknown directive name "' + value[i] + '" in '
+                + 'reportOnlyOmit. Expected one of: ' + VALID_DIRECTIVES.join(', ')
+                + '. (Per CSP Level 3 — https://www.w3.org/TR/CSP3/#csp-directives.)'
+            );
+        }
+        if (out.indexOf(name) === -1) {
+            out.push(name);
+        }
+    }
+    return out;
+}
+
+
 /**
  * Build the header value string from a normalised directive dict.
  *
@@ -482,22 +557,26 @@ function buildHeaderValue(normalised, nonce, nonceTarget) {
 
 /**
  * Return a shallow copy of the normalised directive dict with the
- * report-only-inert directives (`REPORT_ONLY_IGNORED_DIRECTIVES`) removed.
- * Used only when `reportOnly` is true. Pure — never mutates the input, so the
- * full configured set survives for an enforcing factory built from the same
- * directives.
- *
- * @param {object} normalised — validated directive dict from resolveDirectives.
- * @returns {object} a new dict without the report-only-ignored directives.
+ * report-only-inert directives (`REPORT_ONLY_IGNORED_DIRECTIVES`) removed,
+ * plus any consumer-chosen `extraOmit` names (the validated `reportOnlyOmit`
+ * option). Used only when `reportOnly` is true. Pure — never mutates the
+ * input, so the full configured set survives for an enforcing factory built
+ * from the same directives. Called with one argument, behaviour is identical
+ * to the pre-`reportOnlyOmit` shape (inert set only).
+ *
+ * @param {object}    normalised — validated directive dict from resolveDirectives.
+ * @param {string[]} [extraOmit] — validated `reportOnlyOmit` names (default none).
+ * @returns {object} a new dict without the omitted directives.
  * @inner
  * @private
  */
-function stripReportOnlyIgnored(normalised) {
+function stripReportOnlyIgnored(normalised, extraOmit) {
+    var omit = extraOmit || [];
     var out  = {};
     var keys = Object.keys(normalised);
     for (var i = 0; i < keys.length; i++) {
         var name = keys[i];
-        if (REPORT_ONLY_IGNORED_DIRECTIVES.indexOf(name) !== -1) {
+        if (REPORT_ONLY_IGNORED_DIRECTIVES.indexOf(name) !== -1 || omit.indexOf(name) !== -1) {
             continue;
         }
         out[name] = normalised[name];
@@ -604,6 +683,15 @@ function resolveNonceTarget(normalised) {
  *                                               Content-Security-Policy-
  *                                               Report-Only instead of
  *                                               Content-Security-Policy.
+ * @param   {string[]} [opts.reportOnlyOmit=[]] — directive names to ALSO
+ *                                               omit when reportOnly is
+ *                                               true (validated against
+ *                                               the CSP Level 3
+ *                                               whitelist); emitted again
+ *                                               automatically when
+ *                                               reportOnly is false. Inert
+ *                                               and silent in enforce
+ *                                               mode.
  * @param   {boolean} [opts.useNonce=false]    — generate a per-response
  *                                               nonce, stamp it on
  *                                               `req._ginaCspNonce`, and
@@ -616,9 +704,28 @@ function resolveNonceTarget(normalised) {
  * @throws  {Error}                            — when `directives` is
  *                                               missing/empty, contains an
  *                                               unknown directive name, has
- *                                               invalid value shapes, or
+ *                                               invalid value shapes,
  *                                               `useNonce:true` with no
- *                                               script-src/default-src.
+ *                                               script-src/default-src,
+ *                                               `reportOnlyOmit` is
+ *                                               malformed or names an
+ *                                               unknown directive, the
+ *                                               report-only set is empty
+ *                                               after omissions, or
+ *                                               `reportOnlyOmit` omits the
+ *                                               nonce target in report-only
+ *                                               mode.
+ *
+ * @example
+ * // Engine-divergent directive opt-out: omit frame-ancestors from the
+ * // report-only header (clean WebKit console; forgoes the Gecko + Blink
+ * // report signal) — restored automatically at the enforce flip.
+ * var csp = require('gina').plugins.Csp({
+ *     reportOnly: true,
+ *     directives: { 'script-src': ["'self'"], 'frame-ancestors': ["'self'"] },
+ *     reportOnlyOmit: ['frame-ancestors']
+ * });
+ * app.use(csp);
  */
 function Csp(opts) {
     var defaults    = resolveSettingsDefaults();
@@ -627,20 +734,44 @@ function Csp(opts) {
     var directives  = resolveDirectives(merged.directives);
     var reportOnly  = resolveReportOnly(merged.reportOnly);
     var useNonce    = resolveUseNonce(merged.useNonce);
+    var reportOnlyOmit = resolveReportOnlyOmit(merged.reportOnlyOmit);
 
     // Report-only mode: drop directives browsers ignore in a report-only
-    // header (REPORT_ONLY_IGNORED_DIRECTIVES — currently `sandbox`). They apply
-    // no restriction and emit no violation report there, so omitting them is
-    // functionally identical while silencing the browser console warning. They
-    // survive in `directives`, so an enforcing factory built from the same
-    // config still emits them.
+    // header (REPORT_ONLY_IGNORED_DIRECTIVES — currently `sandbox`), plus any
+    // consumer-chosen `reportOnlyOmit` names (typically engine-divergent
+    // directives like frame-ancestors). Both survive in `directives`, so an
+    // enforcing factory built from the same config still emits them.
     var emitDirectives = directives;
     if (reportOnly) {
-        emitDirectives = stripReportOnlyIgnored(directives);
+        emitDirectives = stripReportOnlyIgnored(directives, reportOnlyOmit);
         var dropped = Object.keys(directives).filter(function (d) {
             return !Object.prototype.hasOwnProperty.call(emitDirectives, d);
         });
+        // Split by cause — the warn/throw wording must not claim "ignored by
+        // browsers" for a directive the consumer chose to drop: an opted-out
+        // directive like frame-ancestors IS evaluated + reported by some
+        // engines (Gecko, Blink) in report-only mode.
+        var droppedInert = dropped.filter(function (d) {
+            return REPORT_ONLY_IGNORED_DIRECTIVES.indexOf(d) !== -1;
+        });
+        var droppedOpted = dropped.filter(function (d) {
+            return REPORT_ONLY_IGNORED_DIRECTIVES.indexOf(d) === -1;
+        });
+        var absentOmit = reportOnlyOmit.filter(function (d) {
+            return !Object.prototype.hasOwnProperty.call(directives, d);
+        });
         if (Object.keys(emitDirectives).length === 0) {
+            if (droppedOpted.length > 0) {
+                throw new Error(
+                    '[gina.plugins.Csp] reportOnly:true but the emitted directive set is '
+                    + 'empty after omissions ('
+                    + (droppedInert.length > 0 ? 'ignored by browsers: ' + droppedInert.join(', ') + '; ' : '')
+                    + 'per reportOnlyOmit: ' + droppedOpted.join(', ') + '). '
+                    + 'A report-only policy needs at least one emitted directive that '
+                    + 'produces violation reports (e.g. script-src / default-src). '
+                    + 'Remove entries from reportOnlyOmit or add directives.'
+                );
+            }
             // Mirrors the all-omitted throw in resolveDirectives: an empty CSP
             // is invalid, and a report-only policy made entirely of inert
             // directives reports nothing — surface it at factory (boot) time.
@@ -653,18 +784,39 @@ function Csp(opts) {
                 + 'in report-only mode.'
             );
         }
-        if (dropped.length > 0) {
+        if (droppedInert.length > 0) {
             // Transparency: the emitted header diverges from the configured
             // directives. One line at factory (boot) time — per call, no
             // module-level latch — so the operator knows why a configured
             // directive is absent from the wire.
             console.warn(
                 '[gina.plugins.Csp] reportOnly:true — omitting directive(s) ignored by '
-                + 'browsers in report-only mode: ' + dropped.join(', ') + '. They apply no '
+                + 'browsers in report-only mode: ' + droppedInert.join(', ') + '. They apply no '
                 + 'restriction and emit a browser console warning in report-only mode; they '
                 + 'are included automatically when reportOnly is false.'
             );
         }
+        if (droppedOpted.length > 0) {
+            // Distinct wording — these are NOT browser-inert: some engines
+            // (Gecko + Blink for frame-ancestors) evaluate and report them in
+            // report-only mode; the consumer is forgoing that signal.
+            console.warn(
+                '[gina.plugins.Csp] reportOnly:true — omitting directive(s) per '
+                + 'reportOnlyOmit: ' + droppedOpted.join(', ') + '. These are evaluated and '
+                + 'reported by some engines in report-only mode; you are forgoing that '
+                + 'monitoring signal. They are emitted automatically when reportOnly is '
+                + 'false.'
+            );
+        }
+        if (absentOmit.length > 0) {
+            // Omitting something you don't emit signals a config mistake.
+            // Emitted AFTER the empty-set throws above so a fatally-broken
+            // config surfaces only its throw, not a warn-then-throw sequence.
+            console.warn(
+                '[gina.plugins.Csp] reportOnlyOmit names directive(s) not present in '
+                + 'directives (no-op): ' + absentOmit.join(', ') + '.'
+            );
+        }
     }
 
     var headerName  = reportOnly ? HEADER_NAME_REPORT_ONLY : HEADER_NAME;
@@ -672,9 +824,21 @@ function Csp(opts) {
     var headerValue = buildHeaderValue(emitDirectives);
     // Fail-fast at factory time: a nonce needs a script-governing directive.
     // Resolved from `directives` (not emitDirectives) — the nonce target is
-    // always script-src/default-src, which are never report-only-stripped, so
-    // the two sets agree; the middleware still serialises emitDirectives.
+    // always script-src/default-src, which REPORT_ONLY_IGNORED_DIRECTIVES
+    // never contains and the guard below keeps out of reportOnlyOmit, so the
+    // two sets agree; the middleware still serialises emitDirectives.
     var nonceTarget = useNonce ? resolveNonceTarget(directives) : null;
+    if (nonceTarget && reportOnly && reportOnlyOmit.indexOf(nonceTarget) !== -1) {
+        // The nonce would be stamped on req._ginaCspNonce and mirrored onto
+        // the framework inline <script> tags, but the emitted report-only
+        // policy would never reference it — incoherent header/tag state.
+        throw new Error(
+            '[gina.plugins.Csp] useNonce:true with reportOnly:true requires the '
+            + 'nonce target directive ("' + nonceTarget + '") to be emitted in the '
+            + 'report-only header, but reportOnlyOmit omits it. Remove "'
+            + nonceTarget + '" from reportOnlyOmit.'
+        );
+    }
 
     return function ginaCsp(req, res, next) {
         if (typeof res.getHeader === 'function' && res.getHeader(headerName)) {
@@ -707,6 +871,7 @@ Csp._resolveSettingsDefaults  = resolveSettingsDefaults;
 Csp._mergeOptions             = mergeOptions;
 Csp._resolveDirectives        = resolveDirectives;
 Csp._resolveReportOnly        = resolveReportOnly;
+Csp._resolveReportOnlyOmit    = resolveReportOnlyOmit;
 Csp._resolveUseNonce          = resolveUseNonce;
 Csp._resolveNonceTarget       = resolveNonceTarget;
 Csp._buildHeaderValue         = buildHeaderValue;