gina 0.3.15-alpha.1 → 0.3.15-alpha.2

package/ROADMAP.md

@@ -156,6 +156,27 @@ 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** covers CSP + COEP/COOP/CORP (dynamic / higher-break-risk, deferred to `0.4.0`). 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)** — `gina.plugins.HidePoweredBy()` removes the `X-Powered-By` response header (Express's `X-Powered-By: Express` leaks framework identity). REMOVE shape (`res.removeHeader`), unlike the SET shape of every other plugin in the track. Modest practical value; helmet covers it. | `0.3.16-alpha` | Q2 2026 |
+| 📋 | **Phase 1.5 — `X-DNS-Prefetch-Control` (#HDR9)** — `gina.plugins.XDnsPrefetchControl({ value })`. Default `"off"` (matches helmet). Marginal value — modern browsers mostly ignore the header. | `0.3.16-alpha` | Q3 2026 |
+| 📋 | **Phase 1.5 — `X-XSS-Protection: 0` (#HDR10)** — `gina.plugins.XXssProtection()` emits `0` to DISABLE Chrome's legacy XSS auditor (deprecated; auditor had its own vulnerabilities). Near-zero practical value in 2026 (Chrome dropped the auditor in 78; Firefox / Safari never implemented). | `0.3.16-alpha` | Q3 2026 |
+| 📋 | **Phase 1.5 — `X-Download-Options: noopen` (#HDR11)** — `gina.plugins.XDownloadOptions()` IE8+ legacy header. Modern browsers ignore. Defense-in-depth for IE11 holdouts only. | `0.3.16-alpha` | Q3 2026 |
+| 📋 | **Phase 1.5 — `X-Permitted-Cross-Domain-Policies` (#HDR12)** — `gina.plugins.XPermittedCrossDomainPolicies({ value })`. Restricts Adobe Flash / PDF cross-domain. Flash EOL since 2020; PDF readers mostly ignore. Helmet still ships it. | `0.3.16-alpha` | Q3 2026 |
+| 📋 | **`Content-Security-Policy` (Phase 2 — static directives)** — Opt-in plugin `gina.plugins.Csp({ directives, reportOnly })`. v0 ships static directives only; per-response nonce wiring requires template-render integration and defers to a separate CSP-aware view-layer plugin. `reportOnly: true` emits `Content-Security-Policy-Report-Only` for non-enforcing migration testing. | `0.4.0` | Q1 2027 |
+| 📋 | **`Cross-Origin-{Embedder,Opener,Resource}-Policy` (Phase 2)** — Opt-in plugin `gina.plugins.CrossOriginPolicies({ embedder, opener, resource })` — COEP/COOP/CORP browsing-context isolation. Distinct from CORS (request-side, handled in `core/server.js:1362-1520`). Can break legitimate cross-origin resource loading; opt-in even more conservatively than Phase 1. | `0.4.0` | Q1 2027 |
+
+---
+
 ## 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.2/VERSION

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

package/framework/{v0.3.15-alpha.1 → v0.3.15-alpha.2}/core/plugins/index.js

@@ -32,11 +32,21 @@ function Plugins() {
 
 
     var self =  {
-        Validator   : _require('./lib/validator'),
+        Validator           : _require('./lib/validator'),
         // #CSRF1 — hardened session-cookie wrapper around express-session.
-        Session     : _require('./lib/session'),
+        Session             : _require('./lib/session'),
         // #CSRF2 — signed double-submit token CSRF middleware.
-        Csrf        : _require('./lib/csrf')
+        Csrf                : _require('./lib/csrf'),
+        // #HDR1 — X-Content-Type-Options: nosniff response header.
+        XContentTypeOptions : _require('./lib/x-content-type-options'),
+        // #HDR2 — X-Frame-Options clickjacking-defense response header.
+        XFrameOptions       : _require('./lib/x-frame-options'),
+        // #HDR3 — Referrer-Policy response header.
+        ReferrerPolicy      : _require('./lib/referrer-policy'),
+        // #HDR4 — HSTS (Strict-Transport-Security) response header.
+        Hsts                : _require('./lib/hsts'),
+        // #HDR7 — Origin-Agent-Cluster response header (origin-keyed isolation).
+        OriginAgentCluster  : _require('./lib/origin-agent-cluster')
     };
 
     return self

package/framework/v0.3.15-alpha.2/core/plugins/lib/hsts/README.md

@@ -0,0 +1,144 @@
+# HSTS Plugin (#HDR4)
+
+Opt-in middleware that sets the `Strict-Transport-Security` response
+header on every response, instructing browsers to access the host
+exclusively over HTTPS for the next `maxAge` seconds.
+
+## Why
+
+Once a browser receives a valid HSTS policy from a host, it refuses to
+make plain HTTP requests to that host for the duration of `maxAge` —
+attempts get upgraded to HTTPS before the network even sees them. This
+defeats SSL-stripping attacks where an active MITM intercepts the
+client's first HTTP request and prevents it from ever escalating to
+HTTPS. Once the policy is in place, the attacker has no opportunity to
+sit between the client and the server in plaintext.
+
+The fourth and final Phase 1 plugin on the gina security headers
+track (#HDR1–#HDR4).
+
+## Adoption
+
+One line in the bundle bootstrap (`bundles/<name>/index.js`), after the
+express app is created:
+
+```js
+var express = require('express');
+var hsts    = require('gina').plugins.Hsts();
+var app     = express();
+
+app.use(hsts);
+```
+
+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
+{
+  "hsts": {
+    "maxAge":            15552000,
+    "includeSubDomains": false,
+    "preload":           false
+  }
+}
+```
+
+| Field               | Type    | Default     | Notes                                      |
+|---------------------|---------|-------------|--------------------------------------------|
+| `maxAge`            | number  | `15552000`  | Seconds. Default = 180 days.               |
+| `includeSubDomains` | boolean | `false`     | Apply HSTS to all sub-domains as well.     |
+| `preload`           | boolean | `false`     | Opt into the HSTS preload list.            |
+
+Caller-supplied options always win over settings:
+
+```js
+var hsts = require('gina').plugins.Hsts({
+    maxAge:            63072000,
+    includeSubDomains: true,
+    preload:           true
+});
+```
+
+## Browser-parity invariant on `preload`
+
+`preload: true` requires `includeSubDomains: true` AND `maxAge >=
+31536000` (1 year) per the [HSTS preload-list submission requirements](https://hstspreload.org/#deployment-recommendations).
+The factory throws at call time when the combination is invalid:
+
+```
+[gina.plugins.Hsts] preload=true requires includeSubDomains=true per the
+HSTS preload-list submission requirements — see
+https://hstspreload.org/#deployment-recommendations
+```
+
+```
+[gina.plugins.Hsts] preload=true requires maxAge>=31536000 (1 year)
+per the HSTS preload-list submission requirements; received
+maxAge=15552000. See https://hstspreload.org/#deployment-recommendations
+```
+
+This mirrors the #CSRF1 `SameSite=None`+`Secure` lock and the #HDR2
+`ALLOW-FROM` rejection — fast-fail at bootstrap, the bundle won't start
+with a misconfigured header.
+
+**Why the invariant matters**: the HSTS preload list is the browsers'
+hard-coded HSTS database. Once your hostname is in it, all browsers
+treat HSTS as active from the moment they install the browser update,
+regardless of whether they've ever fetched a response from your host.
+Removal from the preload list takes months and isn't guaranteed —
+opting in is a one-way operation in practical terms. The submission
+requirements exist to keep operators from accidentally locking
+themselves out.
+
+## Choosing values
+
+- **`maxAge`** — start small (`300` = 5 minutes) during initial rollout
+  to bound the blast radius of a mistake; ramp to `15552000` (180 days)
+  for steady state; `63072000` (2 years) is the conventional value for
+  preload-list submission.
+- **`includeSubDomains`** — only enable if you're certain *every*
+  sub-domain (including ones added in the future) will be HTTPS-only.
+  Common foot-gun: `app.example.com` enabling `includeSubDomains` and
+  breaking `legacy.example.com` that's stuck on HTTP.
+- **`preload`** — only opt in once you've run stable in steady-state for
+  weeks, audited every sub-domain, and accepted that removal is slow.
+
+## Spec note — emission gating
+
+This plugin emits the header on **every** response regardless of
+transport. RFC 6797 §7.2 says "An HSTS Host MUST NOT include the STS
+header field in HTTP responses conveyed over non-secure transport".
+However, §8.1 also says the user agent "MUST ignore any present STS
+header field(s)" received over insecure transport — the receiver
+enforces the policy correctly regardless of what the server sends.
+
+The plugin's design favours **proxy-deployment robustness** (no
+dependency on `x-forwarded-proto` being preserved by intermediaries)
+over sender-side spec purity. helmet's `Strict-Transport-Security`
+middleware takes the same approach, so adopters migrating from helmet
+see identical wire behaviour.
+
+Bundles that need strict §7.2 compliance can simply not register the
+plugin in non-HTTPS bundles — the `registration = opt-in` discipline
+covers that case.
+
+## Failure modes
+
+| Condition                                                | Outcome                                              |
+|----------------------------------------------------------|------------------------------------------------------|
+| All fields omitted                                       | Emits `max-age=15552000`                             |
+| `maxAge` is not a non-negative integer                   | Factory throws at call time                          |
+| `preload=true` with `includeSubDomains=false`            | Factory throws with hstspreload.org pointer          |
+| `preload=true` with `maxAge<31536000`                    | Factory throws with hstspreload.org pointer          |
+| `maxAge=0`                                               | Emits `max-age=0` (clears existing HSTS policy)      |
+| Plugin not registered                                    | Header not emitted; browser uses no HSTS policy      |
+| 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 (e.g.
+a generic helmet-style upstream gate) — the first writer wins.

package/framework/v0.3.15-alpha.2/core/plugins/lib/hsts/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "gina-core-plugin-hsts",
+  "version": "1.0.0",
+  "description": "Strict-Transport-Security (HSTS) response header middleware (#HDR4)",
+  "authors": [
+    {
+      "name": "Maritn-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"
+}

package/framework/v0.3.15-alpha.2/core/plugins/lib/hsts/src/main.js

@@ -0,0 +1,270 @@
+/*
+ * 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.
+ */
+'use strict';
+
+/**
+ * HSTS plugin (#HDR4) — emits the `Strict-Transport-Security` response
+ * header on every response, instructing browsers to access the host
+ * exclusively over HTTPS for the next `maxAge` seconds.
+ *
+ * Bundles adopt it with a one-line bootstrap add:
+ *
+ *     var express = require('express');
+ *     var hsts    = require('gina').plugins.Hsts();
+ *     var app     = express();
+ *
+ *     app.use(hsts);
+ *
+ * Three configuration fields per RFC 6797:
+ *
+ *   - `maxAge`              — seconds; default 15552000 (180 days).
+ *   - `includeSubDomains`   — boolean; default false.
+ *   - `preload`             — boolean; default false. Browser-parity
+ *                             invariant: preload=true requires
+ *                             includeSubDomains=true AND maxAge>=31536000
+ *                             (1 year) per the HSTS preload-list
+ *                             submission requirements.
+ *
+ * Browser-parity invariant on `preload` is enforced at factory call
+ * time — the factory throws when the combination is invalid, mirroring
+ * the #CSRF1 SameSite=None+Secure lock and the #HDR2 ALLOW-FROM
+ * rejection.
+ *
+ * **Spec deviation**: this plugin emits the header on every response
+ * regardless of transport. RFC 6797 §7.2 says "An HSTS Host MUST NOT
+ * include the STS header field in HTTP responses conveyed over non-secure
+ * transport" — but §8.1 also says "the UA MUST ignore any present STS
+ * header field(s)" received over insecure transport. The receiver
+ * enforces the policy correctly regardless, so the practical wire
+ * outcome is identical. This plugin matches helmet's behaviour
+ * (emit unconditionally) rather than the sender-side MUST NOT — the
+ * design favours proxy-deployment robustness (no dependency on
+ * x-forwarded-proto being preserved by intermediaries) over sender-side
+ * spec purity. Bundles that need strict §7.2 compliance can simply not
+ * register the plugin in non-HTTPS bundles.
+ *
+ * @module plugins/hsts
+ */
+
+var HEADER_NAME              = 'strict-transport-security';
+var DEFAULT_MAX_AGE          = 15552000;   // 180 days
+var DEFAULT_INCLUDE_SUBDOMS  = false;
+var DEFAULT_PRELOAD          = false;
+var PRELOAD_MIN_MAX_AGE      = 31536000;   // 1 year — HSTS preload-list submission requirement
+
+
+/**
+ * Read the active bundle's `settings.json > hsts.*` block and return the
+ * merged framework defaults.
+ *
+ * Falls back to an empty object when the bundle context is not ready yet
+ * (e.g. `Hsts()` invoked at module-require time, before `onInitialize`).
+ *
+ * @returns {object}
+ * @inner
+ * @private
+ */
+function resolveSettingsDefaults() {
+    var defaults   = {};
+    var pluginConf = {};
+
+    try {
+        var ctx    = getContext();
+        var bundle = ctx && ctx.bundle;
+        var env    = ctx && ctx.env;
+        var conf   = (typeof getConfig === 'function') ? getConfig() : null;
+        if (bundle && env && conf && conf[bundle] && conf[bundle][env]) {
+            var content  = conf[bundle][env].content || {};
+            var settings = content.settings || {};
+            pluginConf   = settings.hsts || {};
+        }
+    } catch (ignored) {
+        pluginConf = {};
+    }
+
+    for (var k in pluginConf) {
+        if (Object.prototype.hasOwnProperty.call(pluginConf, k)) {
+            defaults[k] = pluginConf[k];
+        }
+    }
+
+    return defaults;
+}
+
+
+/**
+ * Merge caller-supplied options on top of the resolved defaults.
+ * Caller-supplied values always win (`hasOwnProperty`-guarded).
+ *
+ * @param {object|undefined} caller
+ * @param {object}           defaults
+ * @returns {object}
+ * @inner
+ * @private
+ */
+function mergeOptions(caller, defaults) {
+    caller = caller || {};
+    var merged = {};
+    for (var dk in defaults) {
+        if (Object.prototype.hasOwnProperty.call(defaults, dk)) merged[dk] = defaults[dk];
+    }
+    for (var ck in caller) {
+        if (Object.prototype.hasOwnProperty.call(caller, ck)) merged[ck] = caller[ck];
+    }
+    return merged;
+}
+
+
+/**
+ * Coerce a value to boolean with explicit defaults.
+ *
+ * @param {*}       value
+ * @param {boolean} fallback
+ * @returns {boolean}
+ * @inner
+ * @private
+ */
+function toBool(value, fallback) {
+    if (typeof value === 'undefined' || value === null) return fallback;
+    if (typeof value === 'boolean') return value;
+    if (typeof value === 'string') {
+        if (/^(true|1|yes|on)$/i.test(value))  return true;
+        if (/^(false|0|no|off)$/i.test(value)) return false;
+    }
+    return fallback;
+}
+
+
+/**
+ * Validate the merged options against the HSTS spec invariants and
+ * return a normalised triplet `{ maxAge, includeSubDomains, preload }`.
+ *
+ * Browser-parity invariant: `preload: true` requires
+ * `includeSubDomains: true` AND `maxAge >= 31536000` (1 year). Per the
+ * HSTS preload-list submission requirements at
+ * https://hstspreload.org/#deployment-recommendations — the factory
+ * throws at call time when the combination is invalid, mirroring the
+ * #HDR2 throw-on-invalid pattern.
+ *
+ * @param {object} merged
+ * @returns {{maxAge: number, includeSubDomains: boolean, preload: boolean}}
+ * @throws  {Error} when maxAge is not a non-negative integer, or when
+ *                  preload=true is not paired with includeSubDomains=true
+ *                  and maxAge>=PRELOAD_MIN_MAX_AGE
+ * @inner
+ * @private
+ */
+function resolveOptions(merged) {
+    var maxAge            = (typeof merged.maxAge === 'undefined' || merged.maxAge === null)
+                                ? DEFAULT_MAX_AGE
+                                : merged.maxAge;
+    var includeSubDomains = toBool(merged.includeSubDomains, DEFAULT_INCLUDE_SUBDOMS);
+    var preload           = toBool(merged.preload, DEFAULT_PRELOAD);
+
+    if (typeof maxAge !== 'number' || !isFinite(maxAge) || maxAge < 0 || Math.floor(maxAge) !== maxAge) {
+        throw new Error(
+            '[gina.plugins.Hsts] maxAge must be a non-negative integer (seconds); '
+            + 'received ' + JSON.stringify(merged.maxAge) + '.'
+        );
+    }
+
+    if (preload) {
+        if (!includeSubDomains) {
+            throw new Error(
+                '[gina.plugins.Hsts] preload=true requires includeSubDomains=true '
+                + 'per the HSTS preload-list submission requirements — see '
+                + 'https://hstspreload.org/#deployment-recommendations'
+            );
+        }
+        if (maxAge < PRELOAD_MIN_MAX_AGE) {
+            throw new Error(
+                '[gina.plugins.Hsts] preload=true requires maxAge>=' + PRELOAD_MIN_MAX_AGE
+                + ' (1 year) per the HSTS preload-list submission requirements; '
+                + 'received maxAge=' + maxAge + '. See '
+                + 'https://hstspreload.org/#deployment-recommendations'
+            );
+        }
+    }
+
+    return { maxAge: maxAge, includeSubDomains: includeSubDomains, preload: preload };
+}
+
+
+/**
+ * Build the header value string from a normalised triplet.
+ *
+ * Per RFC 6797 §6.1, `max-age` MUST appear first; the optional
+ * `includeSubDomains` and `preload` directives are appended in that
+ * order when their fields are true.
+ *
+ * @param   {{maxAge: number, includeSubDomains: boolean, preload: boolean}} opts
+ * @returns {string}
+ * @inner
+ * @private
+ */
+function buildHeaderValue(opts) {
+    var parts = ['max-age=' + opts.maxAge];
+    if (opts.includeSubDomains) parts.push('includeSubDomains');
+    if (opts.preload)           parts.push('preload');
+    return parts.join('; ');
+}
+
+
+/**
+ * Return an express-compatible middleware that sets the
+ * `Strict-Transport-Security` response header.
+ *
+ * Idempotent — if the header is already set by an earlier middleware, the
+ * existing value is preserved and `next()` is called immediately.
+ *
+ * @example
+ * var hsts = require('gina').plugins.Hsts({
+ *     maxAge:            63072000,
+ *     includeSubDomains: true,
+ *     preload:           true
+ * });
+ * app.use(hsts);
+ *
+ * @param   {object}  [opts]
+ * @param   {number}  [opts.maxAge=15552000]            — seconds (180 days default)
+ * @param   {boolean} [opts.includeSubDomains=false]
+ * @param   {boolean} [opts.preload=false]              — preload-list opt-in
+ * @returns {function} — express middleware `(req, res, next) => void`
+ * @throws  {Error} when maxAge is not a non-negative integer, or when
+ *                  preload=true is not paired with includeSubDomains=true
+ *                  and maxAge>=31536000 (1 year)
+ */
+function Hsts(opts) {
+    var defaults    = resolveSettingsDefaults();
+    var merged      = mergeOptions(opts, defaults);
+    var resolved    = resolveOptions(merged);
+    var headerValue = buildHeaderValue(resolved);
+
+    return function ginaHsts(req, res, next) {
+        if (typeof res.getHeader === 'function' && res.getHeader(HEADER_NAME)) {
+            return next();
+        }
+        res.setHeader(HEADER_NAME, headerValue);
+        next();
+    };
+}
+
+
+// Exposed for unit testing. Do not rely on these in application code.
+Hsts._HEADER_NAME             = HEADER_NAME;
+Hsts._DEFAULT_MAX_AGE         = DEFAULT_MAX_AGE;
+Hsts._DEFAULT_INCLUDE_SUBDOMS = DEFAULT_INCLUDE_SUBDOMS;
+Hsts._DEFAULT_PRELOAD         = DEFAULT_PRELOAD;
+Hsts._PRELOAD_MIN_MAX_AGE     = PRELOAD_MIN_MAX_AGE;
+Hsts._resolveSettingsDefaults = resolveSettingsDefaults;
+Hsts._mergeOptions            = mergeOptions;
+Hsts._resolveOptions          = resolveOptions;
+Hsts._buildHeaderValue        = buildHeaderValue;
+Hsts._toBool                  = toBool;
+
+module.exports = Hsts;

package/framework/v0.3.15-alpha.2/core/plugins/lib/origin-agent-cluster/README.md

@@ -0,0 +1,84 @@
+# Origin-Agent-Cluster Plugin (#HDR7)
+
+Opt-in middleware that sets the `Origin-Agent-Cluster: ?1` response
+header on every response, requesting that the browser place this page's
+origin in its own agent cluster (origin-keyed) rather than the default
+site-keyed (eTLD+1) cluster.
+
+## Why
+
+By default, two same-site cross-origin pages (e.g. `app.example.com`
+and `marketing.example.com`) share an agent cluster — they can
+synchronously script each other if either page sets `document.domain`.
+Origin-Agent-Cluster opts the page out of this: it gets its own agent,
+isolated from sibling-origin pages, and `document.domain` becomes a
+no-op.
+
+Two benefits:
+
+1. **Spectre mitigation** — origin-keyed agents are placed in their own
+   OS process where possible, limiting the blast radius of side-channel
+   attacks that leak memory across same-site pages.
+2. **Cleaner isolation contract** — defends against the rare-but-real
+   pattern where a less-trusted same-site origin tries to reach into a
+   trusted page's documents via `document.domain` tricks.
+
+Cost is small: same-site cross-origin pages can no longer use
+`document.domain` to share a same-origin context. Pages that rely on
+this legacy pattern (rare in modern apps) should not opt in.
+
+Per the [HTML spec](https://html.spec.whatwg.org/multipage/document-sequences.html#origin-keyed-agent-clusters)
+and helmet convention, `?1` (boolean true per Structured Header Values
+syntax) is the only value worth emitting. `?0` is the browser default;
+emitting it is a no-op. There is no `enabled` flag in the configuration
+surface — register the plugin to opt in, don't register to opt out.
+
+## Adoption
+
+One line in the bundle bootstrap (`bundles/<name>/index.js`), after the
+express app is created:
+
+```js
+var express            = require('express');
+var originAgentCluster = require('gina').plugins.OriginAgentCluster();
+var app                = express();
+
+app.use(originAgentCluster);
+```
+
+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
+{
+  "originAgentCluster": {}
+}
+```
+
+The block is reserved for future use (e.g. per-route opt-out). Today the
+plugin has no tunable options — the only useful header value is `?1`,
+and the header is unconditionally emitted on every response the
+middleware sees.
+
+## Browser support
+
+Chrome 88+, Edge 88+, Firefox 109+, Safari 15+. Older browsers ignore
+the header silently — safe to register unconditionally.
+
+## Failure modes
+
+| Condition                                                | Outcome                                              |
+|----------------------------------------------------------|------------------------------------------------------|
+| Plugin not registered                                    | Header not emitted; browser uses default site-keyed agent |
+| Header already set by an earlier middleware              | Existing value preserved (idempotent)                |
+| Response already sent (`res.headersSent === true`)       | Node's `setHeader` no-ops; request resumes           |
+| Browser predates the feature                             | Header ignored silently — harmless                   |
+| Same-origin policy relies on `document.domain`           | Will break; do not register the plugin               |
+
+The idempotent behaviour makes the plugin safe to register more than
+once or alongside another middleware that emits the same header (e.g.
+a generic helmet-style upstream gate) — the first writer wins.

package/framework/v0.3.15-alpha.2/core/plugins/lib/origin-agent-cluster/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "gina-core-plugin-origin-agent-cluster",
+  "version": "1.0.0",
+  "description": "Origin-Agent-Cluster response header middleware (#HDR7)",
+  "authors": [
+    {
+      "name": "Maritn-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"
+}