gina 0.5.25 → 0.5.26

package/framework/{v0.5.25 → v0.5.26}/core/server.js

@@ -702,7 +702,13 @@ function Server(options) {
                         isCacheless         : options.conf[self.appName][self.env].isCacheless,
                         routing             : options.conf[self.appName][self.env].routing,
                         allRoutes           : options.conf.routing,
-                        cachePath           : options.conf[self.appName][self.env].cachePath
+                        cachePath           : options.conf[self.appName][self.env].cachePath,
+                        // #COMPLY9 — the transport-posture knobs resolve exactly like
+                        // `scheme` itself: the bundle's settings (already seeded into
+                        // serverOpt above) win, and these fills give env.json's
+                        // per-env `server` block a voice when settings are silent.
+                        requireHttps        : options.conf[self.appName][self.env].server.requireHttps,
+                        allowInsecure       : options.conf[self.appName][self.env].server.allowInsecure
                     }
             );
 
@@ -918,10 +924,28 @@ function Server(options) {
                 throw new Error('[ SERVER ] `settings.json > auth` must be an object.');
             }
 
+            // #COMPLY10 — deny-by-default authorization: an un-annotated route is GATED
+            // rather than open, and opts back out with `param.public: true`. Read HERE,
+            // before the per-route loop, because two of that loop's refusals only apply
+            // while the mode is on. Strict boolean for the same reason as every sibling
+            // flag in this block: a truthy string would leave every un-annotated route
+            // silently UNGATED while the operator believes the bundle is deny-by-default
+            // — the quietly-OFF class this whole block exists to refuse.
+            var _authzDefaultDeny = false;
+            if ( typeof(_authzSettings.requireAuthByDefault) != 'undefined' ) {
+                if ( typeof(_authzSettings.requireAuthByDefault) != 'boolean' ) {
+                    throw new Error('[ SERVER ] `settings.json > auth.requireAuthByDefault` must be a boolean — got '+ JSON.stringify(_authzSettings.requireAuthByDefault) +'. A truthy string would leave every un-annotated route silently UNGATED, so the boot refuses instead.');
+                }
+                _authzDefaultDeny = _authzSettings.requireAuthByDefault;
+            }
+
             var _authzSrcPath     = self.conf[self.appName][self.env].bundlesPath + '/' + self.appName;
             var _authzCount       = 0;
             var _authzRolesCount  = 0;
             var _authzPolicyCount = 0;
+            var _authzPublicCount = 0;
+            var _authzDefaultGatedCount = 0;
+            var _authzWsUngated   = [];   // #B159 — ws routes the mode would otherwise count as gated
             for (var _authzRule in _authzRouting) {
                 var _authzRoute = _authzRouting[_authzRule];
                 if ( typeof(_authzRoute) != 'object' || _authzRoute === null || !_authzRoute.param ) {
@@ -983,6 +1007,84 @@ function Server(options) {
                     _authzGated = true;
                     ++_authzPolicyCount;
                 }
+                // #B159 — a WebSocket route can declare an authorization key, but nothing
+                // can ever enforce it. A `method: "ws"` route is registered on the engine's
+                // extended-CONNECT handler and never reaches `handle()` / `router.route`,
+                // which is where `lib/authz-gate` runs — so the gate is not merely skipped,
+                // it is unreachable by construction. Left accepted, the route would lint
+                // clean, boot, AND be counted in the "Registered N authorization-gated
+                // route(s)" line below: the framework would actively confirm an illusion.
+                // That is precisely the quietly-OFF class the rest of this block refuses
+                // (a truthy-string `requireAuth` already refuses to boot), so a
+                // structurally unenforceable one must refuse too. `/^ws$/i` is the SAME
+                // predicate the ws registration uses, so the two can never disagree about
+                // what a ws route is. Placed after the requireAuth/roles/policy blocks so
+                // `_authzGated` is already final and one check covers all three keys.
+                if ( _authzGated && /^ws$/i.test(_authzRoute.method || '') ) {
+                    throw new Error('[ SERVER ] Route `'+ _authzRule +'`: it is a `method: "ws"` route, so `param.requireAuth` / `param.roles` / `param.policy` can never be enforced on it — a WebSocket handshake is answered by the engine\'s extended-CONNECT handler and never reaches the authorization gate. Authenticate inside the `wsHandler` instead: it receives the full request, so it can inspect headers and cookies and close the socket itself. Remove the authorization key to make that explicit.');
+                }
+                // #COMPLY10 — `param.public`: the explicit exemption from
+                // `auth.requireAuthByDefault`. Linted UNCONDITIONALLY, mode on or off:
+                // a malformed exemption is an author error worth surfacing at the
+                // deploy that INTRODUCES it, not at the later one that enables the mode
+                // (the audit block's rationale below, applied here). Placed after the
+                // requireAuth/roles/policy blocks so `_authzGated` is already final.
+                if ( typeof(_authzRoute.param.public) != 'undefined' ) {
+                    if ( typeof(_authzRoute.param.public) != 'boolean' ) {
+                        throw new Error('[ SERVER ] Route `'+ _authzRule +'`: `param.public` must be a boolean (got `'+ typeof(_authzRoute.param.public) +'`). A truthy string would NOT exempt the route from `auth.requireAuthByDefault`.');
+                    }
+                    if ( _authzRoute.param.public === true ) {
+                        // Same axis, opposite answers. Neither reading is safe: honouring
+                        // `public` silently un-gates an explicitly gated route (fail-open),
+                        // and honouring the gate silently discards what the author wrote.
+                        // `roles` and `policy` both IMPLY `requireAuth`, so they collapse
+                        // into the same contradiction.
+                        if ( _authzGated ) {
+                            throw new Error('[ SERVER ] Route `'+ _authzRule +'`: `param.public: true` contradicts `param.requireAuth` / `param.roles` / `param.policy` on the same route — it cannot be both exempt from authentication and gated by it. Drop one.');
+                        }
+                        ++_authzPublicCount;
+                    }
+                }
+                // #B158 — a GATED route must not also be cached, however it is gated.
+                // Both render-cache serve points run BEFORE the authorization gate: the
+                // engine-agnostic read serves and RETURNS ahead of `router.route` (inside
+                // which the gate runs), and isaac's runs pre-routing, before `req.routing`
+                // even exists — so neither can consult authorization even in principle.
+                // The key is `<release>:<kind>:<bundle>:<url>` with no principal component,
+                // so a cached gated route replays the first authenticated caller's rendered
+                // body to every later anonymous one. Measured live on an isolated boot: a
+                // Bearer-authenticated render was served verbatim, same body and same
+                // render nonce, to the next unauthenticated caller, while the identical
+                // route WITHOUT `cache` correctly answered 401.
+                //
+                // #COMPLY10 shipped this refusal scoped to MODE-gated routes only, so that
+                // enabling the mode could not break a working bundle; the explicitly
+                // annotated case it deliberately left open is the pre-existing hole, and
+                // closing it here is what #B158 is. Explicitly gated + cached is therefore
+                // now refused in BOTH modes.
+                var _authzRouteGated = _authzGated || ( _authzDefaultDeny && _authzRoute.param.public !== true );
+                if (
+                    _authzRouteGated
+                    && typeof(_authzRoute.cache) != 'undefined'
+                    && _authzRoute.cache
+                ) {
+                    throw new Error('[ SERVER ] Route `'+ _authzRule +'`: '+ ( _authzGated ? '`param.requireAuth` / `param.roles` / `param.policy` gate this route' : '`auth.requireAuthByDefault` gates this route' ) +', but it also declares `cache`. The render cache is read BEFORE authorization runs and its key carries no user identity, so the first authenticated response would be replayed to unauthenticated callers. Drop `cache`'+ ( _authzGated ? ', or remove the authorization keys if the route is meant to be open to everyone.' : ', or mark the route `"public": true` if it is meant to be cacheable and open.' ));
+                }
+                if ( _authzDefaultDeny && !_authzGated && _authzRoute.param.public !== true ) {
+                    // #B159 — the mode cannot gate a ws route either (same unreachable
+                    // gate). Counting one would repeat the illusion the explicit refusal
+                    // above exists to stop, so ws routes are excluded from the tally and
+                    // named once instead. A WARN rather than a refusal on purpose: an
+                    // explicit key is an author asserting something false, whereas the
+                    // mode sweeps up every un-annotated route, so refusing here would
+                    // break a working ws bundle the moment the mode is switched on — the
+                    // exact regression #COMPLY10 was scoped to avoid.
+                    if ( /^ws$/i.test(_authzRoute.method || '') ) {
+                        _authzWsUngated.push(_authzRule);
+                    } else {
+                        ++_authzDefaultGatedCount;
+                    }
+                }
                 if ( _authzGated ) {
                     ++_authzCount;
                 }
@@ -1025,6 +1127,46 @@ function Server(options) {
                 _authzLoginRoute = _authzPath;
             }
 
+            // #COMPLY10 — the lockout check. Under deny-by-default a login route that
+            // is not itself exempt bounces to ITSELF: the gate 302s an unauthenticated
+            // caller to the login page, which is gated, which 302s again — the browser
+            // gives up with ERR_TOO_MANY_REDIRECTS and the bundle has locked out every
+            // visitor. It is statically detectable, so it refuses at boot rather than
+            // at the first visitor — the same trade this block already makes for a
+            // non-boolean `requireAuth` (one deploy-time error instead of a production
+            // incident).
+            if ( _authzDefaultDeny ) {
+                if ( !_authzLoginRoute ) {
+                    // Legal and coherent for a pure API / machine-caller bundle (#MS3):
+                    // with no bounce target every unauthenticated request simply gets a
+                    // 401, which is the correct answer for a service. Warn, never refuse
+                    // — the `auth.machine.enabled`-with-no-callers precedent below:
+                    // legal, but worth seeing at boot.
+                    console.warn('[ SERVER ] `auth.requireAuthByDefault` is true and no `auth.loginRoute` is configured — every unauthenticated request to an un-annotated route gets a 401. Correct for an API bundle; a browser-facing bundle almost certainly wants a login route.');
+                } else {
+                    var _authzLoginTarget = null;
+                    for (var _authzLr in _authzRouting) {
+                        var _authzLrRoute = _authzRouting[_authzLr];
+                        if ( typeof(_authzLrRoute) != 'object' || _authzLrRoute === null || typeof(_authzLrRoute.url) != 'string' ) {
+                            continue;
+                        }
+                        // `url` may carry the `,`-separated multi-url form (config.js
+                        // writes it for the webroot auto-redirect), so a match on any
+                        // member counts.
+                        if ( _authzLrRoute.url.split(',').indexOf(_authzLoginRoute) > -1 ) {
+                            _authzLoginTarget = _authzLrRoute;
+                            break;
+                        }
+                    }
+                    if ( !_authzLoginTarget ) {
+                        throw new Error('[ SERVER ] `auth.requireAuthByDefault` is true, but `auth.loginRoute` (`'+ _authzLoginRoute +'`) does not resolve to a route this bundle declares, so the boot cannot verify the login page is reachable without authenticating. Under deny-by-default an unverifiable login target is exactly the config that locks every visitor out — point `auth.loginRoute` at a routing.json rule name.');
+                    }
+                    if ( !_authzLoginTarget.param || _authzLoginTarget.param.public !== true ) {
+                        throw new Error('[ SERVER ] `auth.requireAuthByDefault` is true, but the login route (`'+ _authzLoginRoute +'`) is not marked `"public": true`. The mode would gate it, so an unauthenticated visitor is bounced to the login page, which bounces again — an infinite redirect that locks out every visitor. Add `"public": true` to that route\'s `param`.');
+                    }
+                }
+            }
+
             // #MS3 — machine-caller authentication: lint + precompute at BOOT.
             // `settings.json > auth.machine` declares named machine callers
             // (services, job runners, external systems) whose
@@ -1113,7 +1255,22 @@ function Server(options) {
                     console.warn('[ SERVER ] `auth.machine.enabled` is true but `auth.machine.callers` declares no caller and no `authenticator` is named — machine authentication is ON but can admit nobody.');
                 }
             }
+            // #COMPLY10 — the per-bundle posture map. MERGED mode runs every bundle of a
+            // project in ONE process and this write happens once per init(), so a FLAT
+            // mode flag would be decided by whichever bundle booted LAST: a bundle that
+            // opted into deny-by-default would silently un-gate every one of its routes
+            // the moment a sibling booted without the key. That is a fail-OPEN, and an
+            // invisible one — the single failure direction this control must not have.
+            // Reading the existing map first preserves what earlier bundles wrote.
+            // (`loginRoute` / `machine` stay flat — pre-existing behaviour, untouched.)
+            var _authzByBundle = (
+                process.gina._authConf
+                && process.gina._authConf.byBundle
+                && typeof(process.gina._authConf.byBundle) == 'object'
+            ) ? process.gina._authConf.byBundle : {};
+            _authzByBundle[self.appName] = { requireAuthByDefault: _authzDefaultDeny };
             process.gina._authConf = { loginRoute: _authzLoginRoute, machine: _authzMachine };
+            process.gina._authConf.byBundle = _authzByBundle;
             if ( _authzMachine.enabled === true ) {
                 console.debug('[ BUNDLE ][ server ][ init ] Machine-caller authentication ENABLED — '+ Object.keys(_authzMachine.callers).length +' caller(s)'
                     + ( _authzMachine.authenticator ? ' + authenticator `'+ _authzMachine.authenticator +'`' : '' )
@@ -1128,6 +1285,17 @@ function Server(options) {
                     +' for [ '+ self.appName +' ]'
                     + ( _authzLoginRoute ? ' — login bounce: '+ _authzLoginRoute : ' — no `auth.loginRoute`: unauthenticated requests get a 401' ));
             }
+            if ( _authzDefaultDeny ) {
+                // console.info, NOT console.debug — the shipped default log_level filters
+                // debug, and under a mode that can lock a bundle out, the count of newly
+                // gated routes is the single number an operator needs confirmed at deploy.
+                console.info('[ BUNDLE ][ server ][ init ] Deny-by-default authorization ENABLED for [ '+ self.appName +' ] — '+ _authzDefaultGatedCount +' un-annotated route(s) now require authentication, '+ _authzPublicCount +' marked `public`');
+                // #B159 — say plainly which routes the mode does NOT reach. Silence here
+                // would read as "everything is gated now", which is the whole failure mode.
+                if ( _authzWsUngated.length > 0 ) {
+                    console.warn('[ BUNDLE ][ server ][ init ] `auth.requireAuthByDefault` does NOT cover '+ _authzWsUngated.length +' WebSocket route(s) — '+ _authzWsUngated.join(', ') +'. A ws handshake never reaches the authorization gate, so these stay open unless their `wsHandler` authenticates. Mark them `"public": true` once you have confirmed that is intended.');
+                }
+            }
 
             // ── #COMPLY2 — audit trail: boot resolve + fail-fast lint ──
             // Sibling of the #COMPLY1 registrar above and the #DTO2 registrar before
@@ -1335,6 +1503,72 @@ function Server(options) {
                 console.warn('[releaseWatch] init skipped: '+ (rwInitErr.stack || rwInitErr.message || rwInitErr));
             }
 
+            // ── #COMPLY9 — production transport posture (ZT2) ──────────────────
+            // Outside the `local` scope a bundle resolving a cleartext scheme is
+            // served exactly as configured — both engines' scheme switches default
+            // to cleartext — so the posture is surfaced at boot instead of staying
+            // invisible: warn by default, refuse when the operator asked for
+            // enforcement, acknowledge when the operator asserted the boundary.
+            //
+            //   server.requireHttps  === true  → REFUSE to boot a cleartext bundle
+            //       outside the local scope. The throw lands in this init() try,
+            //       whose catch emergs + flushes + exits BEFORE any listen() — the
+            //       same pre-listen principle as the MCP transport's fail-closed
+            //       start(): the cleartext port is never reachable at all.
+            //   server.allowInsecure === true  → the operator's assertion that TLS
+            //       terminates upstream (mesh sidecar, ingress/LB, reverse proxy —
+            //       the documented h2c topology); the warn becomes one info line.
+            //       Same vocabulary and polarity as `mcp.json > server >
+            //       allowInsecure`.
+            //
+            // Both are strict booleans resolved like `scheme` itself (bundle
+            // settings win, env.json's `server` block fills — the picked-keys
+            // merge above). A non-boolean throws: a truthy string on
+            // `requireHttps` would leave the transport silently UNENFORCED while
+            // the operator believes otherwise — the quietly-OFF class the authz
+            // lints above refuse (`auth.requireAuthByDefault` precedent). The
+            // scope gate is NOT-local, never is-production: custom scopes (e.g. a
+            // `beta`) are neither local nor production, and a production-keyed
+            // gate would silently skip them — the same reasoning as the
+            // stack-trace egress gate. `conf.server.scopeIsLocal` is deliberately
+            // not used (it derives from projects.json `def_scope`, not the live
+            // scope). The scheme test is `!== 'https'`, fail-closed: anything the
+            // engines cannot positively recognise as https is served cleartext
+            // (their scheme switches `default:` to the plain server).
+            var _tpRequireHttps  = serverOpt.requireHttps;
+            var _tpAllowInsecure = serverOpt.allowInsecure;
+            // Type lint first, scope-independent: settings.json boots every
+            // scope, so the dev machine catches the typo before it ships.
+            if ( typeof(_tpRequireHttps) != 'undefined' && typeof(_tpRequireHttps) != 'boolean' ) {
+                throw new Error('[ SERVER ] `settings.json > server.requireHttps` must be a boolean — got '+ JSON.stringify(_tpRequireHttps) +'. A truthy string would leave the transport silently UNENFORCED, so the boot refuses instead.');
+            }
+            if ( typeof(_tpAllowInsecure) != 'undefined' && typeof(_tpAllowInsecure) != 'boolean' ) {
+                throw new Error('[ SERVER ] `settings.json > server.allowInsecure` must be a boolean — got '+ JSON.stringify(_tpAllowInsecure) +'.');
+            }
+            if ( _tpRequireHttps === true && _tpAllowInsecure === true ) {
+                throw new Error('[ SERVER ] `server.requireHttps` and `server.allowInsecure` are both true — they assert opposite postures (enforce https at this bundle vs TLS terminates upstream). Keep exactly one.');
+            }
+            if ( serverOpt.scheme !== 'https' && !self.isLocalScope() ) {
+                if ( _tpRequireHttps === true ) {
+                    throw new Error('[ SERVER ] `server.requireHttps` is true, but bundle `'+ self.appName +'` resolves scheme `'+ serverOpt.scheme +'` in scope `'+ self.scope +'` — the listener would serve cleartext outside the local scope, which is exactly what this knob refuses (the refusal is pre-listen: nothing binds). Switch the bundle to https (`settings.json > server.scheme: "https"` + `server.credentials`), or — if TLS terminates upstream (mesh, ingress, reverse proxy) — replace `requireHttps` with `server.allowInsecure: true`.');
+                }
+                if ( _tpAllowInsecure === true ) {
+                    console.info('[ BUNDLE ][ server ][ init ] transport posture: scheme `'+ serverOpt.scheme +'` in scope `'+ self.scope +'` — allowInsecure asserted (TLS terminates upstream).');
+                } else {
+                    // proxy.json is advisory only — an https:// upstream hostname
+                    // for this scope+env strongly suggests TLS terminates there,
+                    // but only the explicit `allowInsecure` assertion silences
+                    // the warn (a reviewer can tell an audited acknowledgment
+                    // from a leftover; the #COMPLY10 `public`-marker rationale).
+                    var _tpProxyNote = ( typeof(process.gina.PROXY_HOSTNAME) != 'undefined' && /^https:\/\//i.test(process.gina.PROXY_HOSTNAME) )
+                        ? ' proxy.json declares `'+ process.gina.PROXY_HOSTNAME +'` for this scope+env, so TLS likely terminates there.'
+                        : '';
+                    console.warn('[ BUNDLE ][ server ][ init ] transport posture: bundle `'+ self.appName +'` serves plain `'+ serverOpt.scheme +'` in scope `'+ self.scope +'` — the transport at this listener is cleartext.'+ _tpProxyNote +' If TLS terminates upstream (mesh, ingress/LB, reverse proxy — the documented h2c topology), acknowledge with `server.allowInsecure: true`; to enforce https at this bundle, set `server.requireHttps: true`.');
+                }
+            } else if ( _tpRequireHttps === true && serverOpt.scheme === 'https' && !self.isLocalScope() ) {
+                console.info('[ BUNDLE ][ server ][ init ] transport posture: server.requireHttps satisfied — scheme is https.');
+            }
+
             self.emit('configured', false, engine.instance, engine.middleware, self.conf[self.appName][self.env]);
 
         } catch (err) {

package/framework/{v0.5.25 → v0.5.26}/core/template/conf/settings.json

@@ -76,6 +76,18 @@
       "debounceMs": 750,
       "reconcileIntervalMs": 0
     },
+    // #COMPLY9 — production transport posture. Outside the `local` scope a bundle
+    // resolving a cleartext scheme (anything but https) WARNS at boot.
+    // "requireHttps": true  -> refuse to boot the cleartext bundle instead — the
+    //                          refusal is pre-listen, nothing ever binds.
+    // "allowInsecure": true -> acknowledge that TLS terminates upstream (mesh
+    //                          sidecar, ingress/LB, reverse proxy — the documented
+    //                          h2c topology); the warn becomes one info line. Same
+    //                          vocabulary as `mcp.json > server > allowInsecure`.
+    // Strict booleans; setting both is a boot-refused contradiction. Resolved like
+    // `scheme` itself: bundle settings win, env.json's `server` block fills per env.
+    // The keys are deliberately NOT set here — an explicit template default would
+    // shadow env.json's per-env fill.
     // Compare with core/content.encoding
     // This is the prefered order when it comes to respond with compressed content
     "preferedCompressionEncodingOrder": ["br", "deflate", "gzip", "zstdn", "dcb", "dcz", "compress"]
@@ -228,8 +240,32 @@
   //                  },
   //                  "authenticator": null
   //                }
+  //
+  //   requireAuthByDefault — #COMPLY10 deny-by-default authorization.
+  //              false (default) keeps today's posture: a route is open unless it
+  //              declares `requireAuth` / `roles` / `policy`. true INVERTS that for
+  //              THIS bundle — every route requires authentication unless its
+  //              `param` carries `"public": true`. STRICTLY boolean: a truthy
+  //              string would leave every un-annotated route silently UNGATED while
+  //              you believed the bundle was locked down, so it refuses to boot.
+  //              Enable it in a non-production environment FIRST and read the boot
+  //              line, which reports how many routes it just gated.
+  //              The boot also refuses three configs this mode makes dangerous:
+  //                * `"public": true` on a route that ALSO declares an explicit
+  //                  gate key (it cannot be both exempt from auth and gated by it);
+  //                * a login route the mode would gate — it would bounce to itself,
+  //                  an infinite redirect that locks out every visitor;
+  //                * a mode-gated route that also declares `cache` — the render
+  //                  cache is read BEFORE authorization and its key carries no user
+  //                  identity, so a cached gated route would replay one user's
+  //                  authenticated page to anonymous callers.
+  //              The framework's own injected routes ship `"public": true`, so the
+  //              site root, the error page, `/_status` and the upload endpoints keep
+  //              working when you flip this on.
+  //              Changing this needs a bundle restart (boot config).
   "auth": {
     "loginRoute": null,
+    "requireAuthByDefault": false,
     "machine": {
       "enabled": false,
       "callers": {},

package/framework/{v0.5.25 → v0.5.26}/lib/authz-gate/src/main.js

@@ -61,6 +61,32 @@
  * It is a strict NO-OP for every route that declares no authorization key, so an
  * existing bundle is byte-identical.
  *
+ * ## Deny-by-default (#COMPLY10 — opt-in, per bundle)
+ * `settings.json > auth.requireAuthByDefault: true` INVERTS that last sentence for
+ * the bundle that sets it: a route declaring no authorization key is then GATED
+ * rather than open, and a route opts back out with `param.public: true`. Nothing
+ * else about the gate changes — an un-annotated route carries neither `roles` nor
+ * `policy`, so the mode can only ever produce the 401 or the login bounce.
+ *
+ * The exemption is a POSITIVE marker (`public: true`), matching #CSRF2's
+ * `csrfExempt` rationale: a misread leaves the SECURE state. Reusing
+ * `requireAuth: false` was rejected for the opposite reason — it would make one
+ * literal mean "no-op" in a normal bundle and "audited security exemption" in a
+ * deny-by-default one, so a reviewer could not tell an intentional exemption from
+ * a leftover.
+ *
+ * The mode is keyed PER BUNDLE (`_authConf.byBundle`), not flat: merged mode runs
+ * every bundle in one process, and a flat flag would let whichever bundle booted
+ * last decide the posture for all of them — silently un-gating a bundle that had
+ * opted in. See `requireAuthByDefault()` below.
+ *
+ * `core/server.js` refuses to boot on the contradictions the mode makes possible:
+ * `public` alongside an explicit gate key; a login route the mode would gate (which
+ * bounces to itself — an infinite redirect, i.e. total lockout); and a route the
+ * mode gates that also declares `cache`, because both render-cache serve points run
+ * BEFORE this gate and the cache key carries no principal, so a cached gated route
+ * would replay an authenticated body to anonymous callers.
+ *
  * ## The roles contract (#COMPLY1 defines it; the app populates it)
  * `req.session.user.roles` is a plain array of opaque role-name strings — the
  * framework imposes no vocabulary and no role→permission indirection (v1 names
@@ -211,6 +237,57 @@ var getLoginRoute = function () {
     return ( conf && typeof(conf.loginRoute) == 'string' && conf.loginRoute ) ? conf.loginRoute : null;
 };
 
+/**
+ * #COMPLY10 — read the deny-by-default authorization mode for the request's
+ * OWN bundle.
+ *
+ * `core/server.js` lints `settings.json > auth.requireAuthByDefault` at boot and
+ * writes it onto `process.gina._authConf.byBundle[<bundle>]`, so the request path
+ * costs an O(1) property read (the `loginRoute` / `_policies` precedent).
+ *
+ * The per-bundle keying is load-bearing rather than tidy. `_authConf` is written
+ * once per `init()`, and MERGED mode runs every bundle of a project in ONE process
+ * (`core/config.js`), so a flat flag would be overwritten by whichever bundle
+ * booted last: a bundle that enabled the mode would silently un-gate every one of
+ * its routes because a sibling booted after it without the key. That is a
+ * fail-OPEN, and the one failure direction a deny-by-default control must never
+ * have. Keying by `req.routing.bundle` — populated on BOTH dispatch paths — makes
+ * each bundle's posture independent of its boot order.
+ *
+ * Fail-safe direction is deliberately INVERTED here relative to the rest of the
+ * gate: an unidentifiable bundle returns `false` (do not gate). Every other
+ * unknown in this module denies, because denying is the safe direction when the
+ * question is "may this caller through". Here the question is "did an operator
+ * ask for this mode at all", and answering yes on missing evidence would gate a
+ * bundle whose author never opted in — turning a config gap into a total outage.
+ * It is unreachable from dispatch regardless (`core/server.js` skips any route
+ * carrying no `param`, and every matched route carries a `bundle`).
+ *
+ * @param {object} req - the request (reads `req.routing.bundle`).
+ * @returns {boolean} `true` when THIS bundle opted into deny-by-default.
+ * @inner
+ * @private
+ */
+var requireAuthByDefault = function (req) {
+    var conf = ( typeof(process.gina) != 'undefined' && process.gina && process.gina._authConf )
+        ? process.gina._authConf
+        : null;
+
+    if ( !conf || !conf.byBundle || typeof(conf.byBundle) != 'object' ) {
+        return false;
+    }
+
+    var bundle = ( req && req.routing && typeof(req.routing.bundle) == 'string' && req.routing.bundle !== '' )
+        ? req.routing.bundle
+        : null;
+    if ( !bundle ) {
+        return false;
+    }
+
+    var entry = conf.byBundle[bundle];
+    return ( entry && entry.requireAuthByDefault === true ) ? true : false;
+};
+
 /**
  * The authentication predicate — the shape every #COMPLY1 surface reads.
  *
@@ -874,11 +951,75 @@ var runPolicy = function (controller, req, name, user) {
     return denyForbidden(controller, req, 'policy `'+ name +'` did not allow', '403-policy');
 };
 
+/**
+ * Is the matched route gated by authorization at all?
+ *
+ * The ONE runtime answer to that question: `authorizeRequest` branches on it to
+ * decide whether to authenticate, and the render delegates read it to decide
+ * whether an entry may be written to the render cache (#B158). Keeping a single
+ * implementation is the point — a second copy that drifted would either gate a
+ * route the cache still stores (the #B158 leak, reopened) or refuse to store a
+ * route nobody gates.
+ *
+ * Precedence is STRUCTURAL, not conditional, and deliberately so: `param.public`
+ * is consulted only INSIDE the un-annotated branch, so it can never un-gate a
+ * route that carries an explicit key. The boot lint refuses that contradiction
+ * outright, but a hand-built or tampered config must still fail CLOSED without
+ * depending on the lint having run.
+ *
+ * @param {object} req - the request. Reads `req.routing.param.requireAuth`,
+ *                       `param.roles`, `param.policy`, `param.public` and
+ *                       `req.routing.bundle` (for the #COMPLY10 per-bundle mode).
+ * @returns {boolean} `true` when the route requires an authenticated principal.
+ *
+ * @example
+ * // a render delegate, before storing a rendered body
+ * if ( lib.authzGate.isRouteGated(req) ) {
+ *     return; // never cache a body rendered for an authenticated principal
+ * }
+ */
+var isRouteGated = function (req) {
+    if ( !req || !req.routing || !req.routing.param ) {
+        return false;
+    }
+
+    var param = req.routing.param;
+
+    // An explicit key gates the route. `roles` and `policy` each IMPLY
+    // `requireAuth` — an unauthenticated caller can hold no role, and a policy
+    // is handed an authenticated user. Strict shapes only: the boot lint rejects
+    // every other declared form, so an invalid key must never HALF-gate.
+    if ( param.requireAuth === true ) {
+        return true;
+    }
+    if ( Array.isArray(param.roles) && param.roles.length > 0 ) {
+        return true;
+    }
+    if ( typeof(param.policy) == 'string' && param.policy !== '' ) {
+        return true;
+    }
+
+    // Un-annotated from here — the only branch #COMPLY10 inverts. Written as a
+    // `!== true` test on purpose: §15.2 locates `authorizeRequest`'s own strict
+    // equality test on `param.public` by taking the FIRST match of that source
+    // line in this file, to prove the exemption sits inside its un-annotated
+    // branch. Spelling the same form here — in code OR in a comment quoting it —
+    // steals that position and breaks the pin without changing any behaviour,
+    // so do not "tidy" this into the strict-equality form.
+    if ( param.public !== true ) {
+        return requireAuthByDefault(req);
+    }
+
+    return false;   // explicitly exempted from the default gate
+};
+
 /**
  * Authorize a request against the route it matched.
  *
  * NO-OP (returns `true`) unless the route declares an authorization key
- * (`param.requireAuth: true`, `param.roles` and/or `param.policy`). Evaluation order:
+ * (`param.requireAuth: true`, `param.roles` and/or `param.policy`) — or unless the
+ * bundle opted into #COMPLY10 deny-by-default, in which case an un-annotated route
+ * is gated too, and only `param.public: true` exempts it. Evaluation order:
  * **authN → roles → policy** — an unauthenticated caller on a gated route always gets
  * the 401/bounce, never a 403 (it must not learn that the route is role- or
  * policy-restricted, only that it requires signing in). Roles and policy are
@@ -894,6 +1035,8 @@ var runPolicy = function (controller, req, name, user) {
  *                              write the response).
  * @param {object} req        - the request. Reads `req.routing.param.requireAuth`,
  *                              `req.routing.param.roles`, `req.routing.param.policy`,
+ *                              `req.routing.param.public` and `req.routing.bundle`
+ *                              (#COMPLY10),
  *                              `req.session.user` (and its `.roles`),
  *                              `req.headers.authorization` (#MS3, gated routes only),
  *                              `req.isXMLRequest` and `req[method]`; stamps
@@ -931,8 +1074,31 @@ var authorizeRequest = function (controller, req, res) {
 
     // Strictly `=== true`: the boot lint rejects any other type, so by request time the
     // flag is `true`, `false` or absent — and an absent/false flag must never gate.
+    //
+    // `isRouteGated` above answers the same question for callers that need the verdict
+    // without the enforcement (the #B158 render-cache write guard). The two MUST move
+    // together; §15 pins this structure and a truth-table test pins their agreement.
     if ( param.requireAuth !== true && !mustMatchRoles && !mustRunPolicy ) {
-        return true;   // the route declares no authorization — nothing to do
+        // #COMPLY10 — the deny-by-default mode inverts THIS branch, and only this
+        // branch: an un-annotated route becomes gated instead of open.
+        //
+        // `param.public` is tested INSIDE the un-annotated branch rather than
+        // beside it, which is what makes the precedence STRUCTURAL rather than
+        // conditional: a route carrying `public` alongside an explicit gate key
+        // never reaches here at all, so `public` can never un-gate an explicitly
+        // gated route. The boot lint refuses that contradiction outright — this
+        // shape means a hand-built or tampered config still fails CLOSED instead
+        // of depending on the lint having run.
+        if ( param.public === true ) {
+            return true;   // explicitly exempted from the default gate
+        }
+        if ( !requireAuthByDefault(req) ) {
+            return true;   // mode off — the pre-#COMPLY10 no-op, byte-identical
+        }
+        // Mode ON, un-annotated, not exempt: fall through to the authN block below.
+        // `roles` and `policy` are absent by definition on this path, so the only
+        // reachable outcomes are the 401 and the login bounce — a 403 cannot occur
+        // here, which preserves the shipped 401-vs-403 convention with no new code.
     }
 
     // The effective principal: the SESSION user when authenticated (session
@@ -989,6 +1155,7 @@ var authorizeRequest = function (controller, req, res) {
 
 module.exports = {
     authorizeRequest      : authorizeRequest,
+    isRouteGated          : isRouteGated,
     isAuthenticated       : isAuthenticated,
     hasAnyRole            : hasAnyRole,
     registerPolicy        : registerPolicy,

package/framework/{v0.5.25 → v0.5.26}/lib/cmd/bundle/arguments.json

@@ -15,6 +15,7 @@
   "--max-in-flight",
   "--auth-token",
   "--cors-origin",
+  "--allow-insecure",
   "--dry-run",
   "--format"
 ]

package/framework/{v0.5.25 → v0.5.26}/lib/cmd/bundle/help.txt

@@ -295,9 +295,22 @@
                                allowlist (`http(s)://localhost`, `127.0.0.1`,
                                `[::1]` on any port). Comma-separated. Pass
                                `*` to disable the Origin check entirely.
-
-    Default security posture — bind loopback, no auth, Origin allowlist
-    accepts localhost / 127.0.0.1 / [::1] only. For OAuth-protected
-    deployments, place gina behind a reverse proxy (oauth2-proxy, Traefik
-    ForwardAuth, nginx `auth_request`) that handles the OAuth dance and
-    forwards the upstream request.
+      --allow-insecure         Run without a bearer token even when an
+                               ambient protection has been removed. Assert
+                               only when access is restricted upstream (mesh,
+                               NetworkPolicy, authenticating proxy). Also
+                               `mcp.json > server > allowInsecure`.
+
+    Default security posture — bind loopback, Origin allowlist accepts
+    localhost / 127.0.0.1 / [::1] only. On that default a bearer token is
+    optional: the loopback bind and the Origin allowlist are the protection.
+
+    Remove either one and a token becomes REQUIRED — binding a non-loopback
+    address (`--http-host=0.0.0.0`), or disabling the Origin check
+    (`--cors-origin=*`), makes the server refuse to start unless you pass
+    `--auth-token` or `--allow-insecure`. Nothing ever listens unauthenticated.
+
+    For OAuth-protected deployments, place gina behind a reverse proxy
+    (oauth2-proxy, Traefik ForwardAuth, nginx `auth_request`) that handles the
+    OAuth dance and forwards the upstream request — that topology is
+    non-loopback and token-less by design, so it wants `--allow-insecure`.