gina 0.3.15-alpha.1 → 0.3.15-alpha.3

package/ROADMAP.md

@@ -156,6 +156,30 @@ Cross-site request forgery protection. Three-phase defense-in-depth plan aligned
 
 ---
 
+## Web Security Headers
+
+HTTP security response headers as opt-in `gina.plugins.*` middlewares, mirroring the `Session` (#CSRF1) and `Csrf` (#CSRF2/#CSRF3) plugin shape. Each plugin is single-concern, opt-in by default-off, and reads its config from a flat top-level `settings.json` key. Native implementation — no `helmet` dependency. **Phase 1** covers the five modern critical headers (X-Content-Type-Options, X-Frame-Options, Referrer-Policy, HSTS, Origin-Agent-Cluster) — all shipped in `0.3.15-alpha`. **Phase 1.5** covers helmet-parity gap-fill (HidePoweredBy, X-DNS-Prefetch-Control, X-XSS-Protection, X-Download-Options, X-Permitted-Cross-Domain-Policies) — defense-in-depth + parity-with-helmet narrative; modest practical value. **Phase 2** (targeted at `0.4.0-alpha`) covers CSP + COEP/COOP/CORP + combined wrapper — CSP (#HDR5), COEP (#HDR6), COOP (#HDR13), CORP (#HDR14) and the `SecurityHeaders` combined wrapper (#HDR15) all shipped 2026-05-17 — **Phase 2 closed**. CORS handling is separate and already lives in `core/server.js` (request-side).
+
+| Status | Feature | Version | Target |
+| --- | --- | --- | --- |
+| ✅ | **`X-Content-Type-Options: nosniff` middleware** — Opt-in plugin `gina.plugins.XContentTypeOptions()` returns an Express-compatible middleware that emits the `X-Content-Type-Options: nosniff` response header on every response (the only valid value per RFC 7034 / WHATWG Fetch Standard). Adoption is two lines: `var xContentTypeOptions = require('gina').plugins.XContentTypeOptions(); app.use(xContentTypeOptions);`. Idempotent — if an earlier middleware already set the header, the existing value is preserved (safe to stack with helmet-style upstream gates). No `enabled` flag — register to opt in, don't register to opt out. Settings template seeds `xContentTypeOptions: {}` with the block reserved for future fields (per-route opt-out, etc.); future additions do not need an API break. Establishes the per-header response-middleware shape that the rest of Phase 1 (X-Frame-Options, Referrer-Policy, HSTS, Origin-Agent-Cluster) will mirror. 33 unit tests; full suite 5467/5467. | `0.3.15-alpha` | 2026-05-17 |
+| ✅ | **`X-Frame-Options` clickjacking-defense middleware** — Opt-in plugin `gina.plugins.XFrameOptions({ value })`. Settings: `xFrameOptions.value: "DENY"` or `"SAMEORIGIN"` (default `"SAMEORIGIN"`). Caller options always win over settings; values are normalised to uppercase. Validation rejects the legacy `"ALLOW-FROM"` value at factory call time with a dedicated error pointing at the modern `Content-Security-Policy: frame-ancestors` replacement (modern browsers never honoured ALLOW-FROM cross-vendor). Idempotent — first-writer-wins. 51 unit tests. | `0.3.15-alpha` | 2026-05-17 |
+| ✅ | **`Referrer-Policy` middleware** — Opt-in plugin `gina.plugins.ReferrerPolicy({ value })`. Settings: `referrerPolicy.value` is one of the eight W3C tokens (`"no-referrer"`, `"no-referrer-when-downgrade"`, `"origin"`, `"origin-when-cross-origin"`, `"same-origin"`, `"strict-origin"`, `"strict-origin-when-cross-origin"`, `"unsafe-url"`). Default `"strict-origin-when-cross-origin"` matches the browser default since ~2021. Caller options always win over settings; values are normalised to lowercase per the W3C spec's case-insensitive matching. Invalid tokens throw at factory call time with the full eight-token list + W3C spec URL in the message. Idempotent — first-writer-wins. 56 unit tests. | `0.3.15-alpha` | 2026-05-17 |
+| ✅ | **`Strict-Transport-Security` (HSTS) middleware** — Opt-in plugin `gina.plugins.Hsts({ maxAge, includeSubDomains, preload })`. Defaults: `maxAge: 15552000` (180 days), `includeSubDomains: false`, `preload: false`. Caller options always win over settings. Browser-parity invariant: `preload: true` requires `includeSubDomains: true` AND `maxAge >= 31536000` (1 year) per the HSTS preload-list submission requirements; factory throws at call time on invariant violations with a pointer at https://hstspreload.org/. Also throws on non-integer / negative / NaN / Infinity `maxAge`. Header value built per RFC 6797 §6.1 directive order (`max-age=<n>; includeSubDomains; preload`). Spec deviation documented: emits on every response (helmet-aligned) rather than gating HTTPS-only — receiver enforces correctly anyway per RFC 6797 §8.1. Idempotent — first-writer-wins. 69 unit tests. | `0.3.15-alpha` | 2026-05-17 |
+| ✅ | **`Origin-Agent-Cluster: ?1` middleware** — Opt-in plugin `gina.plugins.OriginAgentCluster()` requests origin-keyed agent clustering — same-site cross-origin pages get isolated agents (can no longer reach in via `document.domain`), mitigating one class of Spectre side-channel attack. Per the HTML spec, `?1` (Structured Header boolean true) is the only useful value; no tunable options. Browser support: Chrome 88+, Edge 88+, Firefox 109+, Safari 15+. Mirrors the #HDR1 shape exactly. Idempotent — first-writer-wins. 33 unit tests. **Closes Phase 1 (modern critical coverage).** | `0.3.15-alpha` | 2026-05-17 |
+| ✅ | **Phase 1.5 — `HidePoweredBy` (#HDR8)** — Opt-in plugin `gina.plugins.HidePoweredBy()` removes the `X-Powered-By` response header that gina emits by default at `server.js:2425` (plus `env.json > response.header`). Reduces the attacker's reconnaissance surface — they no longer learn the server stack identity from the response header. **Different SHAPE from the other HDR plugins**: REMOVE (`res.removeHeader`) not SET. No tunable options today (mirrors helmet's no-opts shape). **Two-engine pairing**: Phase 1 covers the Express engine (`server.js:2425` setHeader fires in early framework middleware before user `app.use()` mounts, so `removeHeader` succeeds). Isaac's 15 direct `response.writeHead({ 'X-Powered-By': ... })` call sites bypass the setHeader/removeHeader interface, so the middleware can't reach them on Isaac. **Phase 2 (shipped 2026-05-17) closed the Isaac gap** via the framework-level `server.hidePoweredBy: true` settings flag (default `false`) that the Isaac engine reads at boot — `_setPoweredByHeader(headers)` closure inside `onPath` wraps 14 object-literal sites + 1 inline `if (!options.hidePoweredBy)` guard at the routing.json setHeader site. Bundles pick the right shape: Express → middleware; Isaac → flag; belt-and-suspenders → both (each no-op on the other engine). Idempotent — `removeHeader` is a no-op when the header is absent. 37 unit tests. **Opens Phase 1.5 (helmet-parity gap-fill).** | `0.3.16-alpha` | 2026-05-17 |
+| ✅ | **Phase 1.5 — `X-DNS-Prefetch-Control` (#HDR9)** — Opt-in plugin `gina.plugins.XDnsPrefetchControl({ value })`. Settings: `xDnsPrefetchControl.value` is one of two tokens (`"on"`, `"off"`); default `"off"` matches helmet (privacy-respecting choice — browser does not pre-resolve DNS for unclicked links, so the resolver only sees hostnames the user actually navigates to). **API-shape divergence from helmet**: helmet uses `{ allow: boolean }`; gina uses `{ value: 'on' \| 'off' }` matching the existing single-token-enum convention (HDR2 / HDR3 / HDR6 / HDR13 / HDR14). README documents the helmet-to-gina mapping for migrators. Caller options always win over settings; values are normalised to lowercase. Mirrors the #HDR14 Corp single-enum plugin shape exactly (`resolveSettingsDefaults` + `mergeOptions` + `resolveValue` throw-on-invalid + idempotent first-writer-wins middleware via `res.getHeader`). Marginal practical value in 2026 — modern Chrome / Firefox have their own DNS-prefetch heuristics that mostly ignore the header; defense-in-depth + helmet-parity narrative. 57 unit tests including a negative-invariant lock on the helmet-shape `{ allow: true }` silent-fallback (it does NOT enable DNS prefetching in gina — emits default `off`). | `0.3.16-alpha` | 2026-05-17 |
+| ✅ | **Phase 1.5 — `X-XSS-Protection: 0` (#HDR10)** — Opt-in plugin `gina.plugins.XXssProtection()` emits the literal header `X-XSS-Protection: 0` to DISABLE Chrome's legacy XSS auditor (the auditor itself had its own vulnerabilities; disabling is the modern recommendation per MDN). **The value `0` is deliberate — not a typo**: HEADER_VALUE is the literal string `"0"`, with a negative-invariant test pinning that the value is NOT any `"1"` enable variant. No tunable options (mirrors helmet's no-opts shape + the #HDR1 XContentTypeOptions plugin shape). Use #HDR5 Csp with a strong policy for the actual XSS defense; this header is defense-in-depth + helmet-parity narrative only. Browser status in 2026: Chrome dropped the auditor in v78 (2019); Edge follows Chrome; Firefox / Safari never implemented; IE11 honoured but is EOL. Idempotent — first-writer-wins via `res.getHeader`; if an upstream middleware accidentally emits the unsafe `"1; mode=block"`, this plugin does NOT override it (mount BEFORE the upstream to win). Mirrors the #HDR1 XContentTypeOptions plugin shape (no opts, single fixed value, same `resolveSettingsDefaults` + `mergeOptions` helpers). 37 unit tests including the negative-invariant lock on no-"1"-variant + the string-not-number "0" emission lock. | `0.3.16-alpha` | 2026-05-17 |
+| ✅ | **Phase 1.5 — `X-Download-Options: noopen` (#HDR11)** — Opt-in plugin `gina.plugins.XDownloadOptions()` emits the literal header `X-Download-Options: noopen` on every response. IE-legacy: prevents IE8+ from opening downloads in the site's security context (an old IE vulnerability shape where the "Open" button on a download dialog opened the file in the SITE's origin, allowing XSS-equivalent via downloaded HTML from a trusted site). `noopen` is the only valid value per MSDN. No tunable options (mirrors helmet's no-opts shape + the #HDR1 / #HDR10 plugin shape). Modern browsers (Chrome / Firefox / Safari / Edge) ignore the header silently; only IE10 / IE11 honour it (both EOL since June 2022). Effectively no-op in modern browsers; defense-in-depth + helmet-parity narrative. Idempotent — first-writer-wins via `res.getHeader`. Mirrors the #HDR1 XContentTypeOptions plugin shape exactly. 35 unit tests. | `0.3.16-alpha` | 2026-05-17 |
+| ✅ | **Phase 1.5 — `X-Permitted-Cross-Domain-Policies` (#HDR12)** — Opt-in plugin `gina.plugins.XPermittedCrossDomainPolicies({ value })` emits the `X-Permitted-Cross-Domain-Policies` response header on every response. Settings: `xPermittedCrossDomainPolicies.value` is one of four Adobe spec tokens (`"none"`, `"master-only"`, `"by-content-type"`, `"all"`); default `"none"` matches helmet (most restrictive — no Flash/PDF cross-domain policy files honoured). **API-shape divergence from helmet**: helmet uses `{ permittedPolicies: <enum> }`; gina uses `{ value: <enum> }` matching the existing single-token-enum convention (HDR2 / HDR3 / HDR6 / HDR9 / HDR13 / HDR14). README documents the helmet-to-gina mapping. Mirrors the #HDR14 Corp single-enum plugin shape exactly (`resolveSettingsDefaults` + `mergeOptions` + `resolveValue` throw-on-invalid + idempotent first-writer-wins via `res.getHeader`). Flash EOL since December 2020; Adobe Reader historically honoured the header but most modern PDF readers ignore it; defense-in-depth + helmet-parity narrative. 60 unit tests including a negative-invariant lock on the helmet-shape `{ permittedPolicies }` silent-fallback (it does NOT switch the gina default — emits default `"none"`). **Closes Phase 1.5.** | `0.3.16-alpha` | 2026-05-17 |
+| ✅ | **`Content-Security-Policy` middleware (Phase 2 — static directives)** — Opt-in plugin `gina.plugins.Csp({ directives, reportOnly })`. **Opens Phase 2** of the security-headers track. v0 ships static directives only; per-response nonce wiring requires template-render integration and defers to a future CSP-aware view-layer plugin. Strict whitelist of 27 CSP Level 3 standard directives — unknown directive names throw at factory call time (CSP typos are silent at the browser; fail-fast catches them). Value parsing accepts arrays of source-list tokens (joined with space), pre-formatted strings, `true` (boolean-only directives + `sandbox`), or `false` (omit). `reportOnly: true` emits `Content-Security-Policy-Report-Only` for non-enforcing migration testing. `directives` is required — no sensible cross-bundle default. Mirrors the HDR1-7 shape (idempotent first-writer-wins via `res.getHeader`). 92 unit tests; full suite 5768/5768. HDR6 Coep/Coop/Corp three-plugin split (per wrapper-consistency design) + HDR15 `SecurityHeaders` combined wrapper composing HDR1-7 + HDR5 + HDR6/13/14 to follow. | `0.4.0-alpha` | 2026-05-17 |
+| ✅ | **`Cross-Origin-Embedder-Policy` (COEP) middleware (Phase 2)** — Opt-in plugin `gina.plugins.Coep({ value })`. Settings: `coep.value` is one of three W3C HTML spec tokens (`"require-corp"`, `"credentialless"`, `"unsafe-none"`); default `"require-corp"` matches helmet. Required (paired with `Coop: same-origin` / #HDR13) to enable SharedArrayBuffer and high-resolution `performance.now()` in the page. Caller options always win over settings; values are normalised to lowercase. Mirrors the #HDR3 ReferrerPolicy single-enum shape with throw-on-invalid validation. The `require-corp` default BREAKS embeds without matching CORP/CORS headers — README walks users through the three escape hatches (set CORP via #HDR14, downgrade to `credentialless`, downgrade to `unsafe-none`). Idempotent — first-writer-wins. 56 unit tests. **First of the three Phase 2 cross-origin policies**; HDR13 Coop and HDR14 Corp to follow, then HDR15 SecurityHeaders combined wrapper closes Phase 2. | `0.4.0-alpha` | 2026-05-17 |
+| ✅ | **`Cross-Origin-Opener-Policy` (COOP) middleware (Phase 2)** — Opt-in plugin `gina.plugins.Coop({ value })`. Settings: `coop.value` is one of four W3C HTML spec tokens (`"same-origin"`, `"same-origin-allow-popups"`, `"noopener-allow-popups"`, `"unsafe-none"`); default `"same-origin"` matches helmet. Required (paired with `Coep: require-corp` / #HDR6) to enable cross-origin isolation. Same-origin isolates `window.opener` references on top-level navigation; same-origin-allow-popups is more compat-friendly for OAuth popup flows. The fourth token `noopener-allow-popups` (W3C spec addition, Chrome 119+/Firefox 131+) severs `window.opener` for popups even at same-origin while keeping the popup window open. Caller options always win over settings; values are normalised to lowercase. Mirrors the #HDR6 Coep single-enum shape. The `same-origin` default BREAKS OAuth popup flows where the popup needs to call back into the opener — README walks users through the three escape hatches. Idempotent — first-writer-wins. 61 unit tests. **Second of the three Phase 2 cross-origin policies**; HDR14 Corp follows, then HDR15 SecurityHeaders combined wrapper closes Phase 2. | `0.4.0-alpha` | 2026-05-17 |
+| ✅ | **`Cross-Origin-Resource-Policy` (CORP) middleware (Phase 2)** — Opt-in plugin `gina.plugins.Corp({ value })`. Settings: `corp.value` is one of three W3C HTML spec tokens (`"same-origin"`, `"same-site"`, `"cross-origin"`); default `"same-origin"` matches helmet's per-middleware default. Resource-side complement to #HDR6 Coep's `require-corp` enforcement — cross-origin embeds under `Coep: require-corp` require the embed-target bundle to set `Corp: cross-origin` (or wider) to load. Most restrictive practical default; defends against side-channel attacks that load a resource cross-origin to measure size/timing for fingerprinting. Caller options always win over settings; values are normalised to lowercase. Mirrors the #HDR6 Coep + #HDR13 Coop single-enum shape. The `same-origin` default BREAKS cross-origin embeds when the resource serves at a separate origin from the embedding page — README walks users through the three escape hatches (pick `same-site` for first-party multi-subdomain setups, pick `cross-origin` for publicly-embeddable CDN assets, per-bundle scoping where the page bundle keeps strict + the CDN bundle adopts `cross-origin`). Idempotent — first-writer-wins. 60 unit tests. **Third and final of the three Phase 2 cross-origin policies**; HDR15 SecurityHeaders combined wrapper follows as the closing slice. | `0.4.0-alpha` | 2026-05-17 |
+| ✅ | **`SecurityHeaders` combined wrapper (Phase 2 — closes #HDR + Phase 1.5 extension)** — Opt-in plugin `gina.plugins.SecurityHeaders({...})` composes the full HDR1-14 set in a single mount with one `settings.json` block (`securityHeaders.*`). **Batteries-included safe set**: calling `SecurityHeaders()` with no opts mounts the **12 non-footgun plugins** (xContentTypeOptions, xFrameOptions, referrerPolicy, hsts, originAgentCluster, hidePoweredBy, xDnsPrefetchControl, xXssProtection, xDownloadOptions, xPermittedCrossDomainPolicies, coop, corp) with per-plugin defaults. CSP (#HDR5) and COEP (#HDR6) are opt-in only (CSP throws on missing directives; COEP `require-corp` breaks embeds without CORP). Per-sub-config explicit opt-out via `<key>: false` or `null` (e.g. `SecurityHeaders({ hsts: false })` for HTTP-only bundles). Individual plugins remain mountable independently as power-user escape hatches — the idempotent first-writer-wins pattern means no double-emit when stacking. Mirrors helmet's `helmet()` orchestrator. **Originally shipped 2026-05-17 with 9 sub-plugins** (HDR1-7 + HDR5 + HDR6/13/14) closing Phase 2; **extended 2026-05-17 to 14 sub-plugins** when Phase 1.5 (HDR8-12) closed — wrapper safe-set grew from 7 to 12 plugins. 92 unit tests (was 83 + 9 for the HDR8-12 sub-config opt-out + override coverage). **Closes Phase 2 + Phase 1.5 extension.** | `0.4.0-alpha` | 2026-05-17 |
+
+---
+
 ## Secrets & Configuration
 
 Secrets handling for bundle JSON configs without baking plaintext values into source. Pluggable-backend design with `process.env` as the default; the reserved API surface allows future Vault / SOPS / K8s Secrets backends to slot in without changing call sites or the placeholder syntax.

package/framework/v0.3.15-alpha.3/VERSION

@@ -0,0 +1 @@
+0.3.15-alpha.3

package/framework/v0.3.15-alpha.3/core/plugins/index.js

@@ -0,0 +1,75 @@
+/*
+ * This file is part of the gina package.
+ * Copyright (c) 2009-2026 Rhinostone <contact@gina.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/**
+ * Gina.Core.Plugins Class
+ *
+ * @package    Gina.Core
+ * @author     Rhinostone <contact@gina.io>
+ */
+
+function Plugins() {
+
+    var _require = function(path) {
+        var isCacheless = (process.env.NODE_ENV_IS_DEV == 'false') ? false : true;
+        if (isCacheless) {
+            try {
+                delete require.cache[require.resolve(path)];
+                return require(path)
+            } catch (err) {
+                throw err
+            }
+
+        } else {
+            return require(path)
+        }
+    }
+
+
+    var self =  {
+        Validator           : _require('./lib/validator'),
+        // #CSRF1 — hardened session-cookie wrapper around express-session.
+        Session             : _require('./lib/session'),
+        // #CSRF2 — signed double-submit token CSRF middleware.
+        Csrf                : _require('./lib/csrf'),
+        // #HDR1 — X-Content-Type-Options: nosniff response header.
+        XContentTypeOptions : _require('./lib/security-headers/x-content-type-options'),
+        // #HDR2 — X-Frame-Options clickjacking-defense response header.
+        XFrameOptions       : _require('./lib/security-headers/x-frame-options'),
+        // #HDR3 — Referrer-Policy response header.
+        ReferrerPolicy      : _require('./lib/security-headers/referrer-policy'),
+        // #HDR4 — HSTS (Strict-Transport-Security) response header.
+        Hsts                : _require('./lib/security-headers/hsts'),
+        // #HDR5 — Content-Security-Policy response header.
+        Csp                 : _require('./lib/security-headers/csp'),
+        // #HDR6 — Cross-Origin-Embedder-Policy response header.
+        Coep                : _require('./lib/security-headers/coep'),
+        // #HDR7 — Origin-Agent-Cluster response header (origin-keyed isolation).
+        OriginAgentCluster  : _require('./lib/security-headers/origin-agent-cluster'),
+        // #HDR8 — X-Powered-By response-header removal (helmet-parity gap-fill, opens Phase 1.5).
+        HidePoweredBy       : _require('./lib/security-headers/hide-powered-by'),
+        // #HDR9 — X-DNS-Prefetch-Control response header (helmet-parity gap-fill).
+        XDnsPrefetchControl : _require('./lib/security-headers/x-dns-prefetch-control'),
+        // #HDR10 — X-XSS-Protection: 0 response header — DISABLES Chrome legacy XSS auditor (helmet-parity).
+        XXssProtection      : _require('./lib/security-headers/x-xss-protection'),
+        // #HDR11 — X-Download-Options: noopen response header — IE-legacy (helmet-parity).
+        XDownloadOptions    : _require('./lib/security-headers/x-download-options'),
+        // #HDR12 — X-Permitted-Cross-Domain-Policies response header — Adobe Flash/PDF legacy (closes Phase 1.5).
+        XPermittedCrossDomainPolicies : _require('./lib/security-headers/x-permitted-cross-domain-policies'),
+        // #HDR13 — Cross-Origin-Opener-Policy response header.
+        Coop                : _require('./lib/security-headers/coop'),
+        // #HDR14 — Cross-Origin-Resource-Policy response header.
+        Corp                : _require('./lib/security-headers/corp'),
+        // #HDR15 — Security Headers combined wrapper (composes HDR1-7 + HDR5 + HDR6/13/14).
+        SecurityHeaders     : _require('./lib/security-headers')
+    };
+
+    return self
+};
+
+module.exports = Plugins()

package/framework/v0.3.15-alpha.3/core/plugins/lib/security-headers/README.md

@@ -0,0 +1,243 @@
+# Security Headers Combined Wrapper (#HDR15)
+
+Opt-in middleware that composes the fourteen per-header security
+plugins into a single mount point with one `settings.json` block.
+Closes Phase 2 of the gina Web Security Headers track; extended with
+the Phase 1.5 helmet-parity plugins (HDR8-12) post-Phase-1.5-closure.
+
+## Why
+
+The individual `#HDR` plugins are deliberately single-concern — each
+emits one response header, reads one settings.json key, has its own
+README. That makes each plugin easy to reason about but verbose to
+adopt: bundles wanting all fourteen end up with fourteen `require(...)`
+calls, fourteen `app.use(...)` mounts, and fourteen settings.json
+blocks.
+
+`gina.plugins.SecurityHeaders({...})` is the one-mount + one-config
+convenience layer over the fourteen. Mirrors helmet's `helmet()` shape
+so bundles migrating from helmet find the API familiar.
+
+## Adoption
+
+### Default — batteries-included safe set
+
+One block in the bundle bootstrap (`bundles/<name>/index.js`):
+
+```js
+var myapp           = require('gina');
+var securityHeaders = require('gina').plugins.SecurityHeaders();
+
+myapp.onInitialize(function(event, app) {
+    app.use(securityHeaders);
+    event.emit('complete', app);
+});
+```
+
+With no opts, mounts the **twelve non-footgun plugins** with their
+per-plugin defaults:
+
+| Sub-plugin                                | Header                              | Default value                                |
+|-------------------------------------------|-------------------------------------|----------------------------------------------|
+| `XContentTypeOptions` (HDR1)              | `X-Content-Type-Options`            | `nosniff`                                    |
+| `XFrameOptions` (HDR2)                    | `X-Frame-Options`                   | `SAMEORIGIN`                                 |
+| `ReferrerPolicy` (HDR3)                   | `Referrer-Policy`                   | `strict-origin-when-cross-origin`            |
+| `Hsts` (HDR4)                             | `Strict-Transport-Security`         | `max-age=15552000` (180 days)                |
+| `OriginAgentCluster` (HDR7)               | `Origin-Agent-Cluster`              | `?1`                                         |
+| `HidePoweredBy` (HDR8)                    | `X-Powered-By`                      | **REMOVED** (Express engine only)            |
+| `XDnsPrefetchControl` (HDR9)              | `X-DNS-Prefetch-Control`            | `off`                                        |
+| `XXssProtection` (HDR10)                  | `X-XSS-Protection`                  | `0` (deliberately disables Chrome auditor)   |
+| `XDownloadOptions` (HDR11)                | `X-Download-Options`                | `noopen` (IE-legacy)                         |
+| `XPermittedCrossDomainPolicies` (HDR12)   | `X-Permitted-Cross-Domain-Policies` | `none` (Flash/PDF-legacy)                    |
+| `Coop` (HDR13)                            | `Cross-Origin-Opener-Policy`        | `same-origin`                                |
+| `Corp` (HDR14)                            | `Cross-Origin-Resource-Policy`      | `same-origin`                                |
+
+The two **opt-in-only plugins** (#HDR5 Csp + #HDR6 Coep) are NOT
+mounted by default because they have known footguns:
+
+- **CSP** (#HDR5) throws on missing directives — there's no sensible
+  cross-bundle default since every bundle has its own resource graph.
+- **COEP** (#HDR6) default `require-corp` BREAKS pages that load
+  cross-origin resources without matching CORP / CORS headers.
+
+Bundles that want either must opt in explicitly (see below).
+
+### Opt in to CSP and COEP
+
+```js
+var securityHeaders = require('gina').plugins.SecurityHeaders({
+    csp: {
+        directives: {
+            'default-src': ["'self'"],
+            'script-src':  ["'self'", 'https://cdn.example.com'],
+            'style-src':   ["'self'", "'unsafe-inline'"],
+            'img-src':     ["'self'", 'data:']
+        }
+    },
+    coep: true                              // require-corp default
+});
+app.use(securityHeaders);
+```
+
+`csp: { directives: {...} }` is required when opting in — `csp: {}`
+or `csp: true` will throw at factory call time (CSP needs directives,
+this is a config error). Use `csp: false` (or omit the key) to keep
+CSP off.
+
+### Opt out of a safe-set plugin
+
+```js
+var securityHeaders = require('gina').plugins.SecurityHeaders({
+    hsts: false                             // HTTP-only bundle — HSTS is a no-op anyway
+});
+app.use(securityHeaders);
+```
+
+Per-sub-config `false` (or `null`) skips that plugin even when it's
+in the safe set. Useful for:
+
+- HTTP-only bundles (skip HSTS)
+- Bundles relying on `document.domain` (skip OriginAgentCluster)
+- Multi-domain bundles with permissive cross-origin needs (skip Coop /
+  Corp, set explicit policy elsewhere)
+
+### Override defaults on a safe-set plugin
+
+```js
+var securityHeaders = require('gina').plugins.SecurityHeaders({
+    xFrameOptions:  { value: 'DENY' },      // override SAMEORIGIN default
+    referrerPolicy: { value: 'no-referrer' },
+    hsts:           { maxAge: 31536000, includeSubDomains: true, preload: true }
+});
+app.use(securityHeaders);
+```
+
+Sub-config objects replace the per-plugin defaults wholesale (shallow
+merge — the standalone plugins' own settings.json reads still apply
+underneath, see "Settings precedence" below).
+
+## Configuration
+
+In `bundles/<name>/config/settings.json`:
+
+```jsonc
+{
+  "securityHeaders": {
+    "xContentTypeOptions":           true,
+    "xFrameOptions":                 { "value": "SAMEORIGIN" },
+    "referrerPolicy":                { "value": "strict-origin-when-cross-origin" },
+    "hsts":                          { "maxAge": 15552000, "includeSubDomains": false, "preload": false },
+    "originAgentCluster":            true,
+    "hidePoweredBy":                 true,
+    "xDnsPrefetchControl":           { "value": "off" },
+    "xXssProtection":                true,
+    "xDownloadOptions":              true,
+    "xPermittedCrossDomainPolicies": { "value": "none" },
+    "coop":                          { "value": "same-origin" },
+    "corp":                          { "value": "same-origin" },
+
+    "csp":                           { "directives": { "default-src": ["'self'"] } },
+    "coep":                          { "value": "require-corp" }
+  }
+}
+```
+
+All sub-config keys are optional. Sub-configs absent from `settings.json`
+fall back to the per-plugin defaults (safe-set plugins are mounted;
+CSP / COEP stay opt-in-only).
+
+### Per-sub-config shapes
+
+| Sub-config key                    | Value shape                                                                          | Mount behaviour                                                                  |
+|-----------------------------------|--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|
+| `xContentTypeOptions`             | `true` / `false` / `null` / `{}`                                                     | Default mount; `false` or `null` opts out                                        |
+| `xFrameOptions`                   | `{ value: 'DENY' \| 'SAMEORIGIN' }` / `true` / `false` / `null` / `{}`                | Default mount with SAMEORIGIN                                                     |
+| `referrerPolicy`                  | `{ value: '<one-of-8-W3C-tokens>' }` / `true` / `false` / `null` / `{}`              | Default mount with strict-origin-when-cross-origin                                |
+| `hsts`                            | `{ maxAge, includeSubDomains, preload }` / `true` / `false` / `null` / `{}`           | Default mount with 180-day maxAge                                                 |
+| `csp`                             | `{ directives: {...}, reportOnly: false }` / `false` / `null`                        | Opt-in only; throws on `{}` or `true` (no directives)                            |
+| `coep`                            | `{ value: '<one-of-3-W3C-tokens>' }` / `true` / `false` / `null` / `{}`              | Opt-in only; default require-corp                                                 |
+| `originAgentCluster`              | `true` / `false` / `null` / `{}`                                                     | Default mount                                                                    |
+| `hidePoweredBy`                   | `true` / `false` / `null` / `{}`                                                     | Default mount (Express engine only; Isaac engine writeHead path unaffected)       |
+| `xDnsPrefetchControl`             | `{ value: 'on' \| 'off' }` / `true` / `false` / `null` / `{}`                         | Default mount with `off`                                                          |
+| `xXssProtection`                  | `true` / `false` / `null` / `{}`                                                     | Default mount (emits literal `0` to DISABLE Chrome legacy auditor)               |
+| `xDownloadOptions`                | `true` / `false` / `null` / `{}`                                                     | Default mount (emits `noopen`; IE-legacy)                                         |
+| `xPermittedCrossDomainPolicies`   | `{ value: '<one-of-4-Adobe-tokens>' }` / `true` / `false` / `null` / `{}`            | Default mount with `none`                                                         |
+| `coop`                            | `{ value: '<one-of-4-W3C-tokens>' }` / `true` / `false` / `null` / `{}`              | Default mount with same-origin                                                    |
+| `corp`                            | `{ value: '<one-of-3-W3C-tokens>' }` / `true` / `false` / `null` / `{}`              | Default mount with same-origin                                                    |
+
+## Settings precedence
+
+Three layers, lowest-to-highest:
+
+1. **Per-plugin defaults** (in each plugin's source — e.g. `xFrameOptions` defaults to `SAMEORIGIN`).
+2. **`settings.json > <key>.*`** (each standalone plugin reads its own settings key — e.g. `xFrameOptions.value` in `settings.json`).
+3. **`settings.json > securityHeaders.<key>.*`** (the wrapper reads this and passes to the per-plugin factory).
+4. **Wrapper opts (`SecurityHeaders({...})`)** (caller opts override everything).
+
+The wrapper passes its resolved sub-config to each per-plugin factory
+as `opts`. The per-plugin factory merges its own settings reads, then
+those opts win.
+
+## Power-user escape hatch — individual plugins still mountable
+
+The standalone plugins continue to work independently:
+
+```js
+var csp = require('gina').plugins.Csp({
+    directives: {
+        'default-src': ["'self'"],
+        'script-src':  ["'self'", "'nonce-XXXXX'"]
+    }
+});
+app.use(csp);
+```
+
+Each plugin uses the **idempotent first-writer-wins** pattern (via
+`res.getHeader`), so stacking the wrapper with an upstream individual
+mount produces no double-emit — the first one to set the header wins,
+the second skips.
+
+This means you can mix-and-match: use `SecurityHeaders()` for the
+seven safe-set plugins, mount `gina.plugins.Csp()` separately with a
+per-request nonce, mount nothing for COEP. All three behaviours
+coexist cleanly.
+
+## Per-sub-plugin references
+
+For the full details on each per-header plugin's behaviour, tradeoffs,
+and failure modes, see the standalone READMEs:
+
+- [`gina-core-plugin-x-content-type-options`](../x-content-type-options/README.md) (HDR1)
+- [`gina-core-plugin-x-frame-options`](../x-frame-options/README.md) (HDR2)
+- [`gina-core-plugin-referrer-policy`](../referrer-policy/README.md) (HDR3)
+- [`gina-core-plugin-hsts`](../hsts/README.md) (HDR4)
+- [`gina-core-plugin-csp`](../csp/README.md) (HDR5)
+- [`gina-core-plugin-coep`](../coep/README.md) (HDR6)
+- [`gina-core-plugin-origin-agent-cluster`](../origin-agent-cluster/README.md) (HDR7)
+- [`gina-core-plugin-hide-powered-by`](../hide-powered-by/README.md) (HDR8)
+- [`gina-core-plugin-x-dns-prefetch-control`](../x-dns-prefetch-control/README.md) (HDR9)
+- [`gina-core-plugin-x-xss-protection`](../x-xss-protection/README.md) (HDR10)
+- [`gina-core-plugin-x-download-options`](../x-download-options/README.md) (HDR11)
+- [`gina-core-plugin-x-permitted-cross-domain-policies`](../x-permitted-cross-domain-policies/README.md) (HDR12)
+- [`gina-core-plugin-coop`](../coop/README.md) (HDR13)
+- [`gina-core-plugin-corp`](../corp/README.md) (HDR14)
+
+## Failure modes
+
+| Condition                                                                  | Outcome                                                                       |
+|----------------------------------------------------------------------------|-------------------------------------------------------------------------------|
+| Plugin not registered                                                      | No security headers emitted; browsers apply their built-in defaults           |
+| `SecurityHeaders()` with no opts                                           | Safe-set mounted (HDR1/2/3/4/7/13/14); CSP and COEP skipped                   |
+| Sub-config = `false` or `null`                                             | That plugin skipped — explicit opt-out                                        |
+| Sub-config = `true`                                                        | That plugin mounted with per-plugin defaults (boolean shorthand)              |
+| Sub-config = `{}`                                                          | Same as `true` for safe-set plugins. CSP throws (directives required); COEP mounts with `require-corp` default. |
+| Sub-config = object with invalid keys/values                               | Per-plugin factory throws at call time (matches standalone behaviour)         |
+| Sub-config = string / number / array / function                            | Wrapper throws at call time with the offending sub-config key in the message  |
+| Header already set by an earlier middleware                                | Existing value preserved (idempotent first-writer-wins, per-plugin)           |
+| Response already sent (`res.headersSent === true`)                         | Node's `setHeader` no-ops; request resumes                                    |
+| Stacked with an upstream individual `gina.plugins.<X>` mount               | First writer wins; the second skip is a no-op                                 |
+
+The fail-fast posture (throws at factory call time for invalid
+sub-configs) is inherited from each per-plugin factory. A
+misconfigured bundle won't start — the throw points at the specific
+sub-config that's wrong, with the plugin's standalone error message.

package/framework/v0.3.15-alpha.3/core/plugins/lib/security-headers/coep/README.md

@@ -0,0 +1,134 @@
+# Cross-Origin-Embedder-Policy Plugin (#HDR6)
+
+Opt-in middleware that sets the `Cross-Origin-Embedder-Policy` (COEP)
+response header on every response, controlling which cross-origin
+resources the page may embed.
+
+## Why
+
+COEP is half of the "cross-origin isolation" pair (the other half is
+`Cross-Origin-Opener-Policy` / #HDR13). Setting both to their strictest
+values (`COEP: require-corp` + `COOP: same-origin`) unlocks features
+that browsers gate behind cross-origin isolation:
+
+- `SharedArrayBuffer` — required by WebAssembly threads, `OffscreenCanvas`
+  with multi-threaded rendering, and any code that needs zero-copy
+  shared memory between worker threads.
+- High-resolution `performance.now()` — sub-millisecond timer precision
+  needed for accurate performance profiling. Without isolation, browsers
+  coarsen the resolution to mitigate Spectre side-channel attacks.
+
+COEP also independently provides defense-in-depth against cross-site
+script injection: with `require-corp` set, the browser refuses to
+load any cross-origin resource that doesn't explicitly opt in via
+`Cross-Origin-Resource-Policy` (CORP) or CORS. An attacker who can
+inject a `<script src="https://evil.com/x.js">` tag can't load the
+script unless evil.com returns the matching CORP or CORS header.
+
+Browser support: Chrome 83+, Edge 83+, Firefox 79+, Safari 15.2+.
+
+## Adoption
+
+One block in the bundle bootstrap (`bundles/<name>/index.js`):
+
+```js
+var myapp = require('gina');
+var coep  = require('gina').plugins.Coep();
+
+myapp.onInitialize(function(event, app) {
+    app.use(coep);
+    event.emit('complete', app);
+});
+```
+
+Order with other gina security plugins does not matter — the header is
+emitted on the response, not consumed from the request.
+
+## Configuration
+
+In `bundles/<name>/config/settings.json`:
+
+```jsonc
+{
+  "coep": {
+    "value": "require-corp"
+  }
+}
+```
+
+| Field   | Type   | Default        | Valid values                                       |
+|---------|--------|----------------|----------------------------------------------------|
+| `value` | string | `require-corp` | `require-corp`, `credentialless`, `unsafe-none`    |
+
+### Three values per the W3C HTML spec
+
+| Token            | Behaviour                                                                                  |
+|------------------|--------------------------------------------------------------------------------------------|
+| `require-corp`   | **Default**. Cross-origin resources must opt-in via CORP or CORS, otherwise blocked. Required (paired with `COOP: same-origin`) for `SharedArrayBuffer` and high-res `performance.now()`. |
+| `credentialless` | Cross-origin no-CORS requests sent WITHOUT credentials (cookies, HTTP auth). Less restrictive than `require-corp` but still gates the cross-origin-isolation combo. |
+| `unsafe-none`    | Browser default. No restrictions; equivalent to not setting the header. Use to explicitly opt OUT (e.g. to override a stricter upstream default). |
+
+Caller-supplied options always win over settings:
+
+```js
+var coep = require('gina').plugins.Coep({ value: 'credentialless' });
+```
+
+Tokens are case-insensitive at this layer — values are normalised to
+lowercase before validation and emission. The spec defines them as
+lowercase enumerated strings; browsers parse case-sensitively, so the
+emitted header is always lowercase.
+
+## Tradeoff with the `require-corp` default
+
+The strict default `require-corp` enables the SharedArrayBuffer +
+cross-origin-isolation combo, but BREAKS pages that load cross-origin
+resources (images, fonts, scripts on a CDN, embedded videos) that
+don't carry the matching `Cross-Origin-Resource-Policy` (CORP) or
+CORS header. Symptoms: blocked resources appear as failed network
+requests in DevTools with a
+`NotSameOriginAfterDefaultedToSameOriginByCoep` error.
+
+Options when `require-corp` breaks an embed:
+
+1. **Set CORP on the embedded resource** (preferred) — if you control
+   the origin serving the embed, add `Cross-Origin-Resource-Policy:
+   cross-origin` (or use #HDR14 `gina.plugins.Corp()` on that bundle).
+2. **Downgrade to `credentialless`** — cookies and HTTP auth are
+   stripped on cross-origin no-CORS requests, but no explicit CORP
+   header is required. Compatible with most public CDN content
+   (fonts, images) that don't need credentials.
+3. **Downgrade to `unsafe-none`** — gives up cross-origin isolation
+   entirely. The page can embed anything but loses SharedArrayBuffer
+   and high-res timers.
+
+## Pair with COOP for the SharedArrayBuffer combo
+
+To enable `SharedArrayBuffer` and the rest of the
+cross-origin-isolated-context features, register BOTH plugins together:
+
+```js
+var coep = require('gina').plugins.Coep();                          // require-corp (default)
+var coop = require('gina').plugins.Coop({ value: 'same-origin' });  // default
+app.use(coep);
+app.use(coop);
+```
+
+The page becomes cross-origin-isolated and `window.crossOriginIsolated`
+returns `true`. See the W3C HTML spec section on
+[cross-origin isolation](https://html.spec.whatwg.org/multipage/browsers.html#cross-origin-isolated)
+for the full feature gate.
+
+## Failure modes
+
+| Condition                                                | Outcome                                              |
+|----------------------------------------------------------|------------------------------------------------------|
+| `value` omitted                                          | Defaults to `require-corp`                            |
+| `value` is not one of the 3 W3C tokens                   | Factory throws at call time (bundle won't start)     |
+| Plugin not registered                                    | Header not emitted; browser uses default behaviour   |
+| Header already set by an earlier middleware              | Existing value preserved (idempotent)                |
+| Response already sent (`res.headersSent === true`)       | Node's `setHeader` no-ops; request resumes           |
+
+The idempotent behaviour makes the plugin safe to register more than
+once or alongside another middleware that emits the same header — the
+first writer wins.

package/framework/v0.3.15-alpha.3/core/plugins/lib/security-headers/coep/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "gina-core-plugin-coep",
+  "version": "1.0.0",
+  "description": "Cross-Origin-Embedder-Policy response header middleware (#HDR6)",
+  "authors": [
+    {
+      "name": "Martin-Luther ETOUMAN",
+      "email": "contact@gina.io"
+    },
+    {
+      "name": "Fabrice DELANEAU",
+      "email": "contact@gina.io"
+    }
+  ],
+  "copyright": "Copyright (c) 2009-2026 Rhinostone <contact@gina.io>",
+  "engines": {
+    "node": ">=0.10.22"
+  },
+  "main": "src/main",
+  "license": "MIT",
+  "readmeFilename": "README.md"
+}