gina 0.6.2 → 0.6.3

package/framework/{v0.6.2 → v0.6.3}/core/server.isaac.js

@@ -310,7 +310,8 @@ const slice = Array.prototype.slice;
  * @param {string} options.cachePath - Absolute path to the bundle cache directory
  * @param {boolean} options.isCacheless - True in dev mode; clears local cache on startup
  * @param {object} options.credentials - TLS credentials (privateKey, certificate, ca, passphrase)
- * @param {object} options.allRoutes - Full routing map (used for frontend routing cache)
+ * @param {object} options.allRoutes - Full routing map (no longer read here — the client maps arrive pre-built, see clientRoutingAssets)
+ * @param {{full: object, stripped: object}} options.clientRoutingAssets - Client-served routing maps built once by core/server.js `buildClientRoutingAssets` (#B212) — the full map and the #B66 host-stripped variant; isaac writes them to disk and serves the precompressed files as its fast-path
  * @param {string} options.preferedCompressionEncodingOrder - Ordered list of accepted encodings
  * @param {number} [options.keepAliveTimeout] - Server keep-alive timeout in ms
  * @param {number} [options.headersTimeout] - Server headers timeout in ms
@@ -360,56 +361,20 @@ function ServerEngineClass(options) {
             localCachePathObj.rmSync();
         }
         // For frontend template routing if needed
-        // TODO - Used `options.routing` instead after having filtered `options.allRoutes` vs `options.formsRules` to use only external routes exposed by `"query"` validation
-        // replaced: delete operator + for...in — destructuring rest builds clean objects (#P21, #P22)
-        var _routing = JSON.clone(options.allRoutes);
-        // var _routing = JSON.clone(options.routing);
-        var _routingKeys = Object.keys(_routing);
-        for (var ri = 0; ri < _routingKeys.length; ++ri) {
-            const { _comment, middleware, ...clean } = _routing[_routingKeys[ri]];
-            // #COMPLY1 — the authorization keys are server-side contracts, stripped from
-            // the client-served map: `roles` (and later `policy`) name the bundle's
-            // authorization model — a disclosure to the browser — and `requireAuth`
-            // rides along for consistency. The browser bundle reads none of them
-            // (measured: zero readers in the client src AND in the built artifacts).
-            // `_routing` is a JSON.clone, so rebuilding `param` here can never touch the
-            // live config; the #B66 stripped variant below is cloned FROM this map, so
-            // it inherits the strip.
-            if ( clean.param && typeof(clean.param) == 'object' ) {
-                const { requireAuth, roles, policy, ...cleanParam } = clean.param;
-                // #COMPLY10 — `public` is an authorization key too: under deny-by-default
-                // the set of public routes IS the authentication surface, so serving the
-                // markers hands an anonymous client a free recon map of what it can reach.
-                // Stripped with `delete` rather than by joining the destructuring above,
-                // for two independent reasons: `public` is a strict-mode RESERVED WORD, so
-                // the bare binding form is a SyntaxError (only a renamed binding compiles);
-                // and a separate statement leaves the destructuring line byte-identical to
-                // what the #COMPLY1 tests pin. The `#P21`/`#P22` note at the top of this
-                // loop moved AWAY from `delete` for V8 hidden-class reasons on hot paths —
-                // this loop runs once at boot over a bounded route table, so that rationale
-                // does not apply here.
-                delete cleanParam.public;
-                clean.param = cleanParam;
-            }
-            _routing[_routingKeys[ri]] = clean;
-
-            // reverseRouting is done on the frontend side
-
-        }// EO for routing keys
-
-        // #B66 — a host-stripped variant of the routing map, served to PROXIED clients
-        // so the browser never receives any bundle's INTERNAL scheme://host:port (an
-        // information disclosure) and cross-bundle client toUrl resolves same-origin.
-        // Drop each route's `host` + `hostname`; KEEP `webroot` (the client toUrl path
-        // relies on it). Proxy-host-agnostic + boot-static like the full map above; the
-        // serve-time handler picks stripped-vs-full per request on request._ginaIsProxyHost.
-        // See the #B66 handler branch below.
-        var _routingStripped = JSON.clone(_routing);
-        var _routingStrippedKeys = Object.keys(_routingStripped);
-        for (var si = 0; si < _routingStrippedKeys.length; ++si) {
-            const { host, hostname, ...cleanStripped } = _routingStripped[_routingStrippedKeys[si]];
-            _routingStripped[_routingStrippedKeys[si]] = cleanStripped;
-        }// EO for stripped routing keys
+        // #B212 — the client-served maps (the full map + the #B66 host-stripped
+        // variant, #COMPLY1/#COMPLY10 strip included) are now built ONCE, engine-
+        // agnostically, by core/server.js (buildClientRoutingAssets) and handed to
+        // every engine via options.clientRoutingAssets — one builder, two consumers:
+        // server.js serves the pre-stringified maps from memory in its onRequest
+        // catch-all (the express path, which used to 404 here), while isaac writes
+        // them to disk below and serves the precompressed files as its fast-path.
+        // Rebuilding the maps here would re-create the exact writer/reader drift
+        // the #C3 lesson warns about.
+        var _routing         = ( options.clientRoutingAssets && options.clientRoutingAssets.full ) || null;
+        var _routingStripped = ( options.clientRoutingAssets && options.clientRoutingAssets.stripped ) || null;
+        if ( !_routing ) {
+            console.warn('[ SERVER ][ isaac ] options.clientRoutingAssets missing — the client routing assets (routing.json / routing.stripped.json) will not be written for this boot.');
+        }
 
         // Checking if brotli is installed
         var brotliBin = null;
@@ -2092,20 +2057,39 @@ function ServerEngineClass(options) {
                         localAsset = _strippedRoutingAsset;
                     }
                 }
+                // Slice 3 (SPA Tier 1) — per-variant weak ETag, computed once at init by
+                // core/server.js beside the maps themselves (#B212 single-builder);
+                // ONE weak tag per variant covers this fast-path's content-encoded
+                // file representations too. Kept in sync with the engine-agnostic
+                // server.js handler per the /_gina/* endpoint rule.
+                var _routingAssetEtag = ( request._ginaIsProxyHost === true && options.clientRoutingAssets )
+                    ? options.clientRoutingAssets.strippedEtag
+                    : ( options.clientRoutingAssets ? options.clientRoutingAssets.fullEtag : null );
                 response.setHeader('content-type', localAsset.mime);
                 response.setHeader('vary', 'Origin');
                 // #B66 — a shared cache must not cross-serve the stripped (proxied) and
-                // full (raw) variants under the same URL; mark the proxied variant private.
-                response.setHeader('cache-control', ( request._ginaIsProxyHost === true ) ? 'private, max-age=86400' : 'public, max-age=86400');
+                // full (raw) variants under the same URL; mark the proxied variant
+                // private. Slice 3 (SPA Tier 1): `no-cache` = revalidate-before-use — each
+                // page boot costs one conditional GET (usually a 304), so a restart's
+                // new route table reaches returning browsers immediately instead of
+                // after the old 24h max-age window.
+                response.setHeader('cache-control', ( request._ginaIsProxyHost === true ) ? 'private, no-cache' : 'public, no-cache');
                 response.setHeader('x-content-type-options', 'nosniff');
                 response.setHeader('x-frame-options', 'DENY');
                 response.setHeader('x-xss-protection', '1; mode=block');
+                if (_routingAssetEtag) {
+                    response.setHeader('etag', _routingAssetEtag);
+                }
                 // #HDR8 Phase 2 — gated on settings.json > server.hidePoweredBy
                 // (inline form because this site uses setHeader instead of the
                 // writeHead object-literal headers shape that _setPoweredByHeader covers)
                 if (!options.hidePoweredBy) {
                     response.setHeader('X-Powered-By', 'Gina/'+ GINA_VERSION);
                 }
+                if ( _routingAssetEtag && request.headers['if-none-match'] === _routingAssetEtag ) {
+                    response.statusCode = 304;
+                    return response.end();
+                }
 
                 var filename  =  _(localAsset.path +'/'+ localAsset.file, true);
                 if (acceptEncodingArr) {
@@ -2151,7 +2135,11 @@ function ServerEngineClass(options) {
                 if ( request.method.toUpperCase() === 'GET' ) {
                     var cacheStatus = null;
                     if ( String(server._cacheIsEnabled).toLowerCase() === 'true' ) {
-                        cacheStatus = 'gina-cache';
+                        // #B238 — identifier from the boot-resolved stamp (server.js
+                        // stamps `instance._cacheName` beside `_cacheIsEnabled`; was
+                        // the literal 'gina-cache'). Same value as the shared handle()
+                        // read's mints — the engines agree on the wire by construction.
+                        cacheStatus = server._cacheName;
                     }
 
                     // Importing cache handler (render/output cache goes through the strategy dispatcher)
@@ -2159,6 +2147,14 @@ function ServerEngineClass(options) {
                     // after a restart (the Map is empty on boot): has()/get() fall back to the disk
                     // body + its `.meta` sidecar. == server.cache.path (the writer's opt.path) by
                     // default — both resolve to the top-level `${cachePath}` (${projectPath}/cache).
+                    // #SPA1 — NOTE for anyone adding a per-route guard here: this read
+                    // is PRE-ROUTING. It keys off the raw `request.url` and there is no
+                    // `request.routing` in scope yet, so a `request.routing.negotiate`
+                    // check at this site would be a control that can never fire. A
+                    // negotiable route is kept out of the cache by the WRITERS refusing
+                    // to store it (render-swig / render-nunjucks writeCache) — which is
+                    // precisely why that refusal is load-bearing rather than belt-and-
+                    // braces. Do not "fix" this by adding a dead guard.
                     renderCache.from(server._cached, options.cachePath);
                     var cacheKey        = null
                         , hasCachedKey  = false

package/framework/{v0.6.2 → v0.6.3}/core/server.js

@@ -433,6 +433,124 @@ function _readInstrumentBody(req, cb) {
     req.on('error', function(e) { _finish(e); });
 }
 
+/**
+ * Builds the client-served routing maps from the boot-time global route
+ * table: the full map, and the #B66 host-stripped variant served to proxied
+ * clients.
+ *
+ * #B212 — this is the ONE engine-agnostic builder. It moved here verbatim
+ * from the isaac engine constructor (`server.isaac.js`), where it lived
+ * isaac-only — leaving `/_gina/assets/routing.json` a 404 under any other
+ * engine, in violation of the `/_gina/*` endpoint-sync rule (and the client,
+ * lacking a `response.ok` check — #B213 — then installed the 404 JSON body AS
+ * its routing table). Two consumers, one source of truth: `init()` hands the
+ * maps to the engine via `serverOpt.clientRoutingAssets` (isaac writes them to
+ * disk and serves the precompressed files as its fast-path) and keeps
+ * pre-stringified copies on `self._clientRoutingAssets` for the engine-
+ * agnostic `onRequest` handler (the express path). Rebuilding per engine
+ * would re-create the writer/reader drift the #C3 lesson warns about.
+ *
+ * Runs once at boot over a bounded route table — not a hot path.
+ *
+ * Slice 3 (#SPA1) rebuilt the cut as an ALLOWLIST. The previous shape was a
+ * destructuring-rest DENYLIST (strip `_comment`/`middleware`, then the
+ * #COMPLY1 `requireAuth`/`roles`/`policy` + #COMPLY10 `public` authorization
+ * keys) — but `schema/routing.json` is `additionalProperties: true` at both
+ * the route and `param` levels, so under a denylist every FUTURE key shipped
+ * to any anonymous browser by default; that is exactly how `csrfExempt`,
+ * `param.dto` and `queryTimeout` reached the wire. Under the allowlist the
+ * authorization strip is structural: a key that is not named simply never
+ * ships. The client contract kept here is the MEASURED reader set — client
+ * `getRoute`/`toUrl` read `url`/`webroot`/`bundle`/`hostname` (+ `host` on
+ * raw deployments), iterate `param` for URL-placeholder bindings, test
+ * `requirements` key-presence, and branch on the route being a redirect;
+ * `negotiate` is the content-negotiation capability flag the navigation
+ * layer needs. Everything else — dispatch keys (`param.control`/`file`/
+ * `path`/`title`/…), `cache`, `csrfExempt`, `scopes`, `namespace`,
+ * `middlewareIgnored`, `validator::` requirement bodies — is a server-side
+ * contract and stays home.
+ *
+ * @private
+ * @param {object} allRoutes - The boot-time global (all-bundles) route table (`options.conf.routing`)
+ * @returns {{full: object, stripped: object}} The client-safe full map and the #B66 host-stripped variant (both fresh clones — the live config is never touched)
+ */
+function buildClientRoutingAssets(allRoutes) {
+    var _all = JSON.clone(allRoutes);
+    var _routing = {};
+    // Route-level allowlist — the measured client contract (see the JSDoc above).
+    var _clientRouteKeys = ['url', 'method', 'webroot', 'bundle', 'hostname', 'host', 'negotiate'];
+    var _routingKeys = Object.keys(_all);
+    for (var ri = 0; ri < _routingKeys.length; ++ri) {
+        var _src   = _all[_routingKeys[ri]];
+        var _clean = {};
+        if ( !_src || typeof(_src) != 'object' ) {
+            _routing[_routingKeys[ri]] = _src;
+            continue;
+        }
+        for (var ki = 0; ki < _clientRouteKeys.length; ++ki) {
+            if ( typeof(_src[_clientRouteKeys[ki]]) != 'undefined' ) {
+                _clean[_clientRouteKeys[ki]] = _src[_clientRouteKeys[ki]];
+            }
+        }
+        // `requirements` — plain-regex entries only: the client toUrl reads KEY
+        // PRESENCE (to keep a declared URL variable out of the query string);
+        // a `validator::{...}` body is a server-side validation spec and a
+        // disclosure of the bundle's validation model.
+        if ( _src.requirements && typeof(_src.requirements) == 'object' ) {
+            var _cleanReq = {};
+            var _reqKeys = Object.keys(_src.requirements);
+            for (var qi = 0; qi < _reqKeys.length; ++qi) {
+                if ( !/^validator\:\:/i.test(String(_src.requirements[_reqKeys[qi]])) ) {
+                    _cleanReq[_reqKeys[qi]] = _src.requirements[_reqKeys[qi]];
+                }
+            }
+            _clean.requirements = _cleanReq;
+        }
+        // `param` — URL-placeholder BINDINGS only. A param entry is a binding
+        // iff the route's own url declares `:key` (the client getRoute uses the
+        // binding regex to split URL variables from appended query params);
+        // every other param key is dispatch/authorization vocabulary
+        // (`control`, `file`, `path`, `title`, the #COMPLY1/#COMPLY10 keys, …)
+        // and is a server-side contract. The one dispatch FACT the client
+        // toUrl branches on — "is this a redirect route" — ships as the
+        // derived boolean `isRedirect` instead of the `control` value.
+        if ( _src.param && typeof(_src.param) == 'object' ) {
+            var _bindings = {};
+            var _urlVars  = String(_src.url || '').match(/\:[-_a-zA-Z0-9]+/g) || [];
+            for (var vi = 0; vi < _urlVars.length; ++vi) {
+                var _varName = _urlVars[vi].substr(1);
+                if ( typeof(_src.param[_varName]) != 'undefined' ) {
+                    _bindings[_varName] = _src.param[_varName];
+                }
+            }
+            _clean.param = _bindings;
+            if ( typeof(_src.param.control) == 'string' && /^redirect$/i.test(_src.param.control) ) {
+                _clean.isRedirect = true;
+            }
+        }
+        _routing[_routingKeys[ri]] = _clean;
+
+        // reverseRouting is done on the frontend side
+
+    }// EO for routing keys
+
+    // #B66 — a host-stripped variant of the routing map, served to PROXIED clients
+    // so the browser never receives any bundle's INTERNAL scheme://host:port (an
+    // information disclosure) and cross-bundle client toUrl resolves same-origin.
+    // Drop each route's `host` + `hostname`; KEEP `webroot` (the client toUrl path
+    // relies on it). Proxy-host-agnostic + boot-static like the full map above; the
+    // serve-time handlers pick stripped-vs-full per request (isaac on the #B65
+    // request stamp, the engine-agnostic onRequest handler on its #B65-twin).
+    var _routingStripped = JSON.clone(_routing);
+    var _routingStrippedKeys = Object.keys(_routingStripped);
+    for (var si = 0; si < _routingStrippedKeys.length; ++si) {
+        const { host, hostname, ...cleanStripped } = _routingStripped[_routingStrippedKeys[si]];
+        _routingStripped[_routingStrippedKeys[si]] = cleanStripped;
+    }// EO for stripped routing keys
+
+    return { full: _routing, stripped: _routingStripped };
+}
+
 function Server(options) {
 
     // switching logger flow
@@ -737,6 +855,36 @@ function Server(options) {
                 serverOpt.ioServer = ioServerOpt
             }
 
+            // #B212 — build the client-served routing maps ONCE here, engine-
+            // agnostically, so /_gina/assets/routing.json serves identically under
+            // every engine: isaac consumes these via serverOpt for its
+            // precompressed-file fast-path, and the engine-agnostic onRequest
+            // handler below serves the pre-stringified copies from memory (the
+            // express path, which used to fall through to routing and 404).
+            // Built BEFORE `new Engine(serverOpt)` — isaac reads them in its
+            // constructor.
+            // TODO - Use the per-bundle `routing` instead of `allRoutes` after having
+            // filtered `allRoutes` vs `formsRules` to use only external routes exposed
+            // by `"query"` validation
+            var _clientRoutingAssets = buildClientRoutingAssets(serverOpt.allRoutes);
+            serverOpt.clientRoutingAssets = _clientRoutingAssets;
+            self._clientRoutingAssets = {
+                full     : JSON.stringify(_clientRoutingAssets.full),
+                stripped : JSON.stringify(_clientRoutingAssets.stripped)
+            };
+            // Slice 3 (#SPA1) — weak per-variant ETags, computed once: the maps are
+            // boot-static, and the serve paths answer If-None-Match with a 304 under
+            // `no-cache` (revalidate) semantics. This closes the staleness window the
+            // old `max-age=86400` left open — a returning browser could dispatch on a
+            // day-old table for up to 24h after a restart. Weak tags (`W/"…"`) so ONE
+            // tag per variant covers isaac's content-encoded file representations too.
+            self._clientRoutingAssets.fullEtag =
+                'W/"' + crypto.createHash('sha1').update(self._clientRoutingAssets.full).digest('hex').substr(0, 16) + '"';
+            self._clientRoutingAssets.strippedEtag =
+                'W/"' + crypto.createHash('sha1').update(self._clientRoutingAssets.stripped).digest('hex').substr(0, 16) + '"';
+            serverOpt.clientRoutingAssets.fullEtag     = self._clientRoutingAssets.fullEtag;
+            serverOpt.clientRoutingAssets.strippedEtag = self._clientRoutingAssets.strippedEtag;
+
             Engine = require('./server.' + ((typeof (serverOpt.engine) != 'undefined' && serverOpt.engine != '') ? serverOpt.engine : 'express'));
             var engine = new Engine(serverOpt);
 
@@ -1355,7 +1503,7 @@ function Server(options) {
                     throw new Error('[ SERVER ] `settings.json > audit.chain.secret` must be a non-empty string.');
                 }
                 if ( typeof(_auditSettings.chain.secret) == 'string' && /\$\{/.test(_auditSettings.chain.secret) ) {
-                    throw new Error('[ SERVER ] `settings.json > audit.chain.secret` carries an unresolved `${...}` placeholder — the named variable is not set at config-load time. Note that `${secret:GINA_*}` names can never resolve (the CLI moves every GINA_* variable out of process.env before config load); use a non-GINA variable name, or set GINA_AUDIT_SECRET.');
+                    throw new Error('[ SERVER ] `settings.json > audit.chain.secret` carries an unresolved `${...}` placeholder — only the anchored `${secret:KEY}` form is substituted at config load; bare `${VAR}` and mixed strings pass through as literals. Use `${secret:KEY}` with the variable exported in the environment the bundle starts from, or set GINA_AUDIT_SECRET.');
                 }
             }
             var _auditChainEnabled = !!( _auditSettings.chain && _auditSettings.chain.enabled === true );
@@ -1899,6 +2047,17 @@ function Server(options) {
             if ( typeof(instance._cacheIsEnabled) == 'undefined' ) {
                 instance._cacheIsEnabled = self.conf[self.appName][self.env].server.cache.enable;
             }
+            // #B238 — the Cache-Status identifier, resolved ONCE from the post-fold
+            // server.cache (`name` when valid, else `gina-cache`) and stamped on the
+            // engine instance both engines read (isaac: `server._cacheName`; the
+            // engine-agnostic hit/miss mints: `self.instance._cacheName`). One
+            // resolution, three readers — the identifier cannot disagree across
+            // engines or hit/miss outcomes. Unconditional beside the sibling
+            // scalars above, so the mint sites read it unguarded (same trust as
+            // `_cacheIsEnabled`).
+            if ( typeof(instance._cacheName) == 'undefined' ) {
+                instance._cacheName = lib.RenderCache.resolveCacheName(self.conf[self.appName][self.env].server.cache);
+            }
 
             // #B115 — publish the engine so the form-validator's server-side `query`
             // rule can hand its hand-built controller the LIVE instance (one engine
@@ -3983,6 +4142,16 @@ function Server(options) {
             if ( typeof(request.headers['x-gina-popin-name']) != 'undefined' ) {
                 ginaHeaders.popin.name = request.headers['x-gina-popin-name'];
             }
+            // #SPA1 — content-negotiation signal. `X-Gina-Navigate: fragment` asks a
+            // NEGOTIABLE route (routing.json `negotiate: true`) for its layoutless body
+            // instead of the full page. Parked here with the other gina headers rather
+            // than overloading `X-Requested-With`, which popin / link / validator all
+            // already send and which the render + error paths already fork on.
+            // Unknown values are deliberately NOT rejected — they fall through to the
+            // full page, so extending the vocabulary later is backward-compatible.
+            if ( typeof(request.headers['x-gina-navigate']) != 'undefined' ) {
+                ginaHeaders.navigate = String(request.headers['x-gina-navigate']).trim().toLowerCase();
+            }
             if ( typeof(request.headers['x-gina-form-rule']) != 'undefined' ) {
                 var rule = request.headers['x-gina-form-rule'].split(/\@/);
                 ginaHeaders.form.rule = rule[0];
@@ -4030,6 +4199,58 @@ function Server(options) {
                 return response.end(JSON.stringify({ status: 'healthy', timestamp: new Date().toISOString() }));
             }
 
+            // ── /_gina/assets/routing.json — client routing map (always-on, public) ─────
+            // (#B212) Engine-agnostic mirror of the Isaac fast-path (server.isaac.js
+            // ~:2079). Under isaac the fast-path answers first with the precompressed
+            // file variants, so this handler is what serves the map under any other
+            // engine (express) — where the asset previously fell through to routing
+            // and 404'd, and the client (no response.ok check — #B213) then installed
+            // the 404 JSON body AS its routing table. Serves the maps built once at
+            // init by buildClientRoutingAssets(). GET only + the isaac header set;
+            // X-Powered-By / X-Request-Id are already emitted above for every
+            // onInstance response, so they are inherited, not re-set.
+            if (
+                request.method.toUpperCase() === 'GET'
+                && /\/_gina\/assets\/routing\.json$/i.test(request.url)
+                && self._clientRoutingAssets
+            ) {
+                // #B65-twin — per-request proxied classification (keep in sync with
+                // the core/server.isaac.js #B65 block + the core/router.js #B67 twin):
+                // proxied iff the inbound Host is port-less (heuristic, disabled by
+                // process.gina._proxyRequireForwarded — #B152) OR an explicit
+                // X-Forwarded-Host is present. Computed inline because the #B65 stamp
+                // (request._ginaIsProxyHost) is isaac-request-path-only and the #B67
+                // twin runs at routing time — after this handler.
+                var _croutHost    = request.headers.host || request.headers[':authority'];
+                var _croutProxied = (
+                    ( _croutHost && !/\:[0-9]+$/.test(_croutHost)
+                        && process.gina._proxyRequireForwarded !== true )
+                    || request.headers['x-forwarded-host']
+                ) ? true : false;
+                var _croutEtag = ( _croutProxied === true )
+                    ? self._clientRoutingAssets.strippedEtag
+                    : self._clientRoutingAssets.fullEtag;
+                response.setHeader('content-type', 'application/json; charset=utf8');
+                response.setHeader('vary', 'Origin');
+                // #B66 — a shared cache must not cross-serve the stripped (proxied) and
+                // full (raw) variants under the same URL; mark the proxied variant
+                // private. Slice 3 (#SPA1): `no-cache` = revalidate-before-use — the
+                // per-variant weak ETag turns each page boot into one conditional GET
+                // (usually a 304), so a restart's new route table reaches returning
+                // browsers immediately instead of after a 24h max-age window.
+                response.setHeader('cache-control', ( _croutProxied === true ) ? 'private, no-cache' : 'public, no-cache');
+                response.setHeader('x-content-type-options', 'nosniff');
+                response.setHeader('x-frame-options', 'DENY');
+                response.setHeader('x-xss-protection', '1; mode=block');
+                response.setHeader('etag', _croutEtag);
+                if ( request.headers['if-none-match'] === _croutEtag ) {
+                    response.statusCode = 304;
+                    return response.end();
+                }
+                response.statusCode = 200;
+                return response.end( ( _croutProxied === true ) ? self._clientRoutingAssets.stripped : self._clientRoutingAssets.full );
+            }
+
             // ── /_gina/metrics — Prometheus exposition (always-on, opt-in via app.json) ──
             // (#OBS1 slice 2) Engine-agnostic mirror of the Isaac handler. Method gate
             // is GET only; IP allowlist comes from app.json `metrics.allowFrom` (default
@@ -6263,7 +6484,9 @@ function Server(options) {
         }
         // #RC5 — ONE header string, set AND logged from the same var (the prior dual
         // construction at setHeader + console.info was a drift hazard).
-        var _cs = 'gina-cache; hit'
+        // #B238 — identifier from the boot-resolved stamp (was the literal
+        // 'gina-cache'); default unchanged when server.cache.name is unset.
+        var _cs = self.instance._cacheName + '; hit'
             + (_remaining !== null ? '; ttl=' + _remaining : '')
             + (source ? '; detail=' + source : '');
         res.setHeader('Cache-Status', _cs);
@@ -6305,6 +6528,12 @@ function Server(options) {
         var _method = ( /http\/2/.test(self.conf[self.appName][self.env].server.protocol) ) ? req.headers[':method'] : req.method;
         if ( !/^get$/i.test(_method || req.method || '') ) { return false; }
         if ( !req.routing || !req.routing.cache ) { return false; }
+        // #SPA1 — never SERVE a negotiable route from the output cache. The key has no
+        // shape dimension and this serve point runs before the shape is resolved, so a
+        // hit could replay a fragment to a page request. The writer refuses too
+        // (render-swig writeCache), making this defence-in-depth rather than the only
+        // guard — but it is stated at BOTH ends so the invariant is local to each site.
+        if ( req.routing.negotiate === true ) { return false; }
         if ( String(self.instance._cacheIsEnabled).toLowerCase() !== 'true' ) { return false; }
         // No L2 store wired (memory/fs bundle, or boot degraded) → nothing to warm here;
         // isaac already served any L1 hit, and express memory/fs read is a later slice.
@@ -6367,7 +6596,8 @@ function Server(options) {
             // deliberately NOT claimed — whether the render's writeCache stores is not
             // knowable here, and headers are flushed before it settles.
             if ( !res.headersSent ) {
-                res.setHeader('Cache-Status', 'gina-cache; fwd=uri-miss');
+                // #B238 — identifier from the boot-resolved stamp (was the literal 'gina-cache').
+                res.setHeader('Cache-Status', self.instance._cacheName + '; fwd=uri-miss');
             }
             return false; // miss → render normally
         }
@@ -6685,6 +6915,13 @@ function Server(options) {
                     // req.routing.param.culture as the highest-priority
                     // culture source (URL `/fr/...` → req.culture='fr').
                     culturePrefix       : routing[name].culturePrefix || false,
+                    // #SPA1 — per-route content-negotiation capability. Declares that
+                    // this route may answer in more than one shape, so the render cache
+                    // (whose key carries no shape dimension) must not serve or store it.
+                    // Read at the request-pipeline boundary, BEFORE the cache serve
+                    // points — which is precisely why the capability is route-declared
+                    // rather than derived inside render().
+                    negotiate           : routing[name].negotiate || false,
                     // We clone because we are going to modify it while comparing urls
                     param               : JSON.clone(routing[name].param),
                     // We clone because we are going to modify it while routing (.splice(..))

package/framework/{v0.6.2 → v0.6.3}/core/template/boilerplate/bundle/index.js

@@ -32,13 +32,15 @@ var ${bundle} = require('gina');
 //    // var session = ${bundle}.plugins.Session(expressSession);
 //    //
 //    // Redis — multi-pod / K8s (requires: npm install ioredis)
-//    // Configure connectors.json: { "myRedis": { "connector": "redis", "host": "...", "port": 6379, "ttl": 86400 } }
-//    // expressSession.name = 'myRedis';
+//    // Configure connectors.json: { "session": { "connector": "redis", "host": "...", "port": 6379, "ttl": 86400 } }
 //    //
 //    // SQLite — dev / staging / single-pod (requires: Node >= 22.5.0, zero npm deps)
-//    // Configure connectors.json: { "myDb": { "connector": "sqlite", "database": ":memory:", "ttl": 86400 } }
-//    // expressSession.name = 'myDb';
+//    // Configure connectors.json: { "session": { "connector": "sqlite", "database": ":memory:", "ttl": 86400 } }
 //    //
+//    // The store factory keys on express-session's function name — the literal
+//    // "session", which is read-only and cannot be re-pointed — so the
+//    // connectors.json entry MUST be named "session"; its `connector` field
+//    // selects the backend (#B206).
 //    // var StoreClass = new SessionStore(expressSession);  // returns connector-specific Store class
 //    //
 //    // Recommended: keep the session secret out of tracked source via the

package/framework/{v0.6.2 → v0.6.3}/core/template/conf/settings.json

@@ -144,6 +144,16 @@
     // refuses boot (a non-expiring L2 key is orphaned on a release-namespace change):
     //   "type": "redis",
     //   "store": "cacheRedis"   // connectors.json: { "cacheRedis": { "connector": "redis", "host": "127.0.0.1", "port": 6379 } }
+    // #B238 — optional `name`: the RFC 9211 Cache-Status identifier this bundle's
+    // render/output cache reports on the wire (default "gina-cache"). A letter, then
+    // up to 63 of [A-Za-z0-9._-] (a conservative RFC 8941 token subset); an invalid
+    // value is ignored with a boot warn. When `server.hidePoweredBy` is true and the
+    // cache is enabled, leaving `name` unset logs a boot warn (the wire still names
+    // the framework) — set any token (e.g. "cache") to close the disclosure, or
+    // explicitly "gina-cache" to keep the default wire and silence the warn.
+    // Deliberately NOT declared here: a template-declared default would read as
+    // operator-set and mute that warn framework-wide.
+    //   "name": "cache",
     "type": "memory"
   },
   // #CSRF1 — session-cookie defaults applied by gina.plugins.Session(expressSession).

package/framework/{v0.6.2 → v0.6.3}/lib/cache/README.md

@@ -116,10 +116,18 @@ Every GET response carries a `Cache-Status` header indicating cache outcome:
 
 | Value | Meaning |
 |-------|---------|
-| `gina-cache; uri-miss` | No cached entry for this URL |
+| `gina-cache; fwd=uri-miss` | No cached entry for this URL (RFC 9211 §2.2 form) |
 | `gina-cache; hit; ttl=NNN` | Hit — `NNN` seconds remaining (absolute TTL) |
 | `gina-cache; hit; ttl=NNN; max-age=MMM` | Hit — `NNN` seconds in current idle window, `MMM` seconds until absolute ceiling |
 
+`gina-cache` is the default identifier — `server.cache.name` (settings.json
+`cache` block) replaces it with an operator-chosen RFC 8941 token (a letter,
+then up to 63 of `[A-Za-z0-9._-]`); every parameter after it is unchanged.
+When `server.hidePoweredBy` is true and the cache is enabled, leaving `name`
+unset logs a boot warn (the wire still names the framework); set any token
+(e.g. `cache`) to close the disclosure, or explicitly `gina-cache` to keep
+the default wire and silence the warn.
+
 ---
 
 ### Storage backends

package/framework/{v0.6.2 → v0.6.3}/lib/cmd/audit/verify.js

@@ -23,10 +23,10 @@ var CmdHelper = require('./../helper');
  * `<project>/logs/audit-<bundle>-<env>.jsonl`).
  *
  * Key resolution: `settings.json > audit.chain.secret` (a `${secret:VAR}`
- * placeholder is resolved from `process.env[VAR]` — config-load substitution
- * does not run offline, and `${secret:GINA_*}` names can never resolve
- * because the CLI sweeps GINA_* out of process.env), then `GINA_AUDIT_SECRET`
- * through the framework env reader.
+ * placeholder is resolved here because config-load substitution does not run
+ * offline — read from the framework env reader first, then `process.env[VAR]`,
+ * so GINA_-prefixed names swept out of process.env by the CLI still resolve,
+ * #B156), then `GINA_AUDIT_SECRET` through the same two-tier read.
  *
  * Exit codes: `0` chain intact (warnings, if any, are printed — read them) ·
  * `1` chain BROKEN · `2` usage/config error (no trail file, no key, bad --env).
@@ -191,9 +191,11 @@ function Verify(opt, cmd) {
 
     /**
      * Resolves the signing key: `audit.chain.secret` (literal, or a
-     * `${secret:VAR}` placeholder resolved from `process.env[VAR]`), then
-     * `GINA_AUDIT_SECRET` through the framework env reader (direct
-     * `process.env` fallback for non-CLI contexts).
+     * `${secret:VAR}` placeholder read from the framework env reader first,
+     * then `process.env[VAR]` — the CLI sweep moves GINA_*-prefixed keys out
+     * of `process.env`, so the two-tier read is what lets a shell-exported
+     * variable resolve in this offline process, #B156), then
+     * `GINA_AUDIT_SECRET` through the same two-tier read.
      *
      * @inner
      * @private
@@ -212,9 +214,9 @@ function Verify(opt, cmd) {
         if ( secret ) {
             var m = secret.match(/^\$\{secret:([^}]+)\}$/);
             if ( m ) {
-                secret = process.env[m[1]] || null;
+                secret = ( typeof(getEnvVar) == 'function' && getEnvVar(m[1]) ) || process.env[m[1]] || null;
                 if ( !secret ) {
-                    console.error('`audit.chain.secret` names `${secret:'+ m[1] +'}` but `'+ m[1] +'` is not set in this shell. Export it, or set GINA_AUDIT_SECRET. (Note: `${secret:GINA_*}` names can never resolve — the CLI sweeps GINA_* out of process.env.)');
+                    console.error('`audit.chain.secret` names `${secret:'+ m[1] +'}` but `'+ m[1] +'` is not set in this environment. Export it before running the command, or set GINA_AUDIT_SECRET.');
                     process.exit(2);
                     return false;
                 }

package/framework/{v0.6.2 → v0.6.3}/lib/cmd/bundle/mcp-start.js

@@ -155,10 +155,15 @@ function MCPStart(opt, cmd) {
         // Loud, one-time notice about the tools that look session-scoped.
         warnSessionScopedTools(mcpDoc.tools);
 
-        // Framework package version — the user-facing server version.
+        // Framework package version — the user-facing server version. Read
+        // GINA_DIR through the framework env reader first: the CLI sweep
+        // empties process.env of GINA_* keys, so the direct read alone made
+        // every CLI-launched server degrade to the '0.0.0' catch below.
         var packVersion = null;
         try {
-            var packPath = _(process.env.GINA_DIR + '/package.json', true);
+            var ginaDir  = (typeof getEnvVar === 'function' && getEnvVar('GINA_DIR'))
+                           || process.env.GINA_DIR;
+            var packPath = _(ginaDir + '/package.json', true);
             packVersion = require(packPath).version;
         } catch (pkgErr) {
             packVersion = '0.0.0';
@@ -364,15 +369,16 @@ function MCPStart(opt, cmd) {
      * Resolves the HTTP bind host. Precedence:
      *   1. `--http-host=<host>` CLI flag
      *   2. `mcp.json > server > httpHost`
-     *   3. `process.env.GINA_HOST_V4` — INERT under the CLI. `filterArgs()`
-     *      moves every GINA_* key into `process.gina` and deletes it from
-     *      `process.env`, so this read is always undefined there.
-     *      Deliberately NOT converted to `getEnvVar` the way the auth-token
-     *      tier was: `host_v4` is the address clients CONNECT to (commonly a
-     *      LAN address), never a bind address — reviving this tier would move
-     *      the default bind OFF loopback and expose the transport. The correct
-     *      replacement is `bind_host` / `GINA_BIND_HOST`, tracked separately.
-     *   4. `'127.0.0.1'` — in practice the effective default, per (3).
+     *   3. `GINA_BIND_HOST` — the framework env reader first, then the raw
+     *      process environment (for embedders that never ran the CLI sweep).
+     *      This is the control plane's dedicated BIND key, same bind/connect
+     *      separation as `bin/cli`. The former `GINA_HOST_V4` tier was
+     *      removed (#B157): it was inert under the CLI (the sweep empties
+     *      the process environment of GINA_* keys), and reviving it would
+     *      have moved the default bind OFF loopback — `host_v4` is the
+     *      address clients CONNECT to (commonly a LAN address), never a
+     *      bind address.
+     *   4. `'127.0.0.1'`
      *
      * @private
      * @param   {object} mcpDoc
@@ -384,7 +390,10 @@ function MCPStart(opt, cmd) {
         if (mcpDoc && mcpDoc.server && typeof(mcpDoc.server.httpHost) === 'string' && mcpDoc.server.httpHost) {
             return mcpDoc.server.httpHost;
         }
-        var env = process.env.GINA_HOST_V4;
+        // #B157 — bind_host, never host_v4: the string guard below also keeps
+        // a sweep-coerced boolean from ever reaching the bind.
+        var env = (typeof getEnvVar === 'function' && getEnvVar('GINA_BIND_HOST'))
+                  || process.env.GINA_BIND_HOST;
         if (typeof(env) === 'string' && env) return env;
         return '127.0.0.1';
     };