gina 0.5.26 → 0.6.0

package/framework/{v0.5.26 → v0.6.0}/core/plugins/lib/session/src/main.js

@@ -8,7 +8,7 @@
 'use strict';
 
 /**
- * Session plugin (#CSRF1) — hardened wrapper around `express-session`.
+ * Session plugin (#CSRF1, #COMPLY4) — hardened wrapper around `express-session`.
  *
  * Bundles adopt it with a one-line swap in their bootstrap:
  *
@@ -26,6 +26,18 @@
  * Browser-parity invariant: `SameSite=None` without `Secure` is rejected at
  * factory call time (matching browser behaviour).
  *
+ * Absolute session timeout (#COMPLY4, opt-in): `session({ absoluteTimeout:
+ * <ms> })` — or the `settings.json > session.absoluteTimeout` default, bundle
+ * code winning (`false` disables) — caps an AUTHENTICATED session's total
+ * lifetime, measured from the `_ginaCreatedAt` anchor `req.login()` stamps at
+ * rotation (manual-bind consumers are anchored lazily, one request late). An
+ * over-age session is destroyed on its next request and the request proceeds
+ * with a fresh anonymous one — indistinguishable from a naturally-expired
+ * record. This composes with idle expiry, which already exists: the cookie
+ * `maxAge` and the store record TTL both roll with activity; this cap does
+ * not. Without the option the factory returns express-session's middleware
+ * untouched.
+ *
  * @module plugins/session
  */
 
@@ -48,6 +60,7 @@ function resolveSettingsDefaults() {
     var defaults   = { sameSite: 'lax', httpOnly: true, secure: 'auto' };
     var cookieConf = {};
 
+    var sessionConf = {};
     try {
         var ctx    = getContext();
         var bundle = ctx && ctx.bundle;
@@ -56,11 +69,12 @@ function resolveSettingsDefaults() {
         if (bundle && env && conf && conf[bundle] && conf[bundle][env]) {
             var content  = conf[bundle][env].content || {};
             var settings = content.settings || {};
-            var session  = settings.session || {};
-            cookieConf   = session.cookie || {};
+            sessionConf  = settings.session || {};
+            cookieConf   = sessionConf.cookie || {};
         }
     } catch (ignored) {
-        cookieConf = {};
+        sessionConf = {};
+        cookieConf  = {};
     }
 
     if (typeof cookieConf.sameSite === 'string') {
@@ -92,9 +106,118 @@ function resolveSettingsDefaults() {
         defaults.secure = cookieConf.secure;
     }
 
+    // #COMPLY4 — absolute-timeout default (ms). Opt-in: absent means none.
+    if (typeof sessionConf.absoluteTimeout !== 'undefined') {
+        if (typeof sessionConf.absoluteTimeout !== 'number'
+            || !isFinite(sessionConf.absoluteTimeout)
+            || sessionConf.absoluteTimeout <= 0
+        ) {
+            throw new Error(
+                '[gina session] settings.json > session.absoluteTimeout must be a positive number of milliseconds'
+                + ' — got: ' + JSON.stringify(sessionConf.absoluteTimeout)
+            );
+        }
+        defaults.absoluteTimeout = sessionConf.absoluteTimeout;
+    }
+
     return defaults;
 }
 
+/**
+ * Resolve the effective absolute-timeout value: the bundle option wins over
+ * the settings default; `false` / `null` in bundle code disables it outright.
+ * The gina-only key is STRIPPED from the options so express-session never
+ * sees it.
+ *
+ * @param   {object} options  - the (mutated) session factory options
+ * @param   {object} defaults - `resolveSettingsDefaults()` output
+ * @returns {(number|null)}     effective cap in ms, or null when disabled
+ * @throws  {Error} when the bundle-supplied value is not a positive number
+ * @inner
+ * @private
+ */
+function resolveAbsoluteTimeout(options, defaults) {
+    if (Object.prototype.hasOwnProperty.call(options, 'absoluteTimeout')) {
+        var v = options.absoluteTimeout;
+        delete options.absoluteTimeout;
+        if (v === false || v === null) {
+            return null;
+        }
+        if (typeof v !== 'number' || !isFinite(v) || v <= 0) {
+            throw new Error(
+                '[gina session] absoluteTimeout must be a positive number of milliseconds'
+                + ' (or false to disable the settings default) — got: ' + JSON.stringify(v)
+            );
+        }
+        return v;
+    }
+    return (typeof defaults.absoluteTimeout === 'number') ? defaults.absoluteTimeout : null;
+}
+
+/**
+ * Wrap the express-session middleware with the absolute-timeout enforcement
+ * (#COMPLY4).
+ *
+ * After the session loads: an authenticated session without a numeric
+ * `_ginaCreatedAt` anchor is stamped (manual-bind consumers — `req.login()`
+ * stamps it at rotation itself; anonymous sessions are never touched, so
+ * `saveUninitialized: false` semantics are preserved). A session whose anchor
+ * is older than the cap is destroyed via its own `regenerate()` — the request
+ * proceeds with a fresh anonymous session, exactly as a naturally-expired
+ * record behaves. Fail-closed: when the record cannot be destroyed
+ * (regenerate error, or no regenerate on the provider) the authentication is
+ * dropped locally at minimum.
+ *
+ * @param   {function} mw         - the middleware express-session returned
+ * @param   {number}   absoluteMs - the effective cap in milliseconds
+ * @returns {function}              wrapping middleware `(req, res, next)`
+ * @inner
+ * @private
+ */
+function makeAbsoluteTimeoutMiddleware(mw, absoluteMs) {
+    return function ginaSessionAbsoluteTimeout(req, res, next) {
+        mw(req, res, function onSessionReady(err) {
+            if (err) {
+                return next(err);
+            }
+            var sess = req.session;
+            if (!sess || typeof sess !== 'object') {
+                return next();
+            }
+            if (sess.user && typeof sess._ginaCreatedAt !== 'number') {
+                // authenticated without an anchor (manual bind, or a corrupt
+                // anchor) — stamp now; enforcement starts from here
+                sess._ginaCreatedAt = Date.now();
+                return next();
+            }
+            if (typeof sess._ginaCreatedAt === 'number'
+                && (Date.now() - sess._ginaCreatedAt) > absoluteMs
+            ) {
+                if (typeof sess.regenerate === 'function') {
+                    return sess.regenerate(function onAbsoluteTimeoutExpired(regenErr) {
+                        if (regenErr && req.session && typeof req.session === 'object') {
+                            // fail-closed: the record could not be destroyed —
+                            // drop the authentication locally at minimum
+                            req.session.user = null;
+                            delete req.session._ginaCreatedAt;
+                        }
+                        next();
+                    });
+                }
+                // no regenerate() on this provider: fail-closed locally,
+                // destroying the record when the provider allows it
+                sess.user = null;
+                delete sess._ginaCreatedAt;
+                if (typeof sess.destroy === 'function') {
+                    return sess.destroy(function onAbsoluteTimeoutDestroyed() { next(); });
+                }
+                return next();
+            }
+            next();
+        });
+    };
+}
+
 /**
  * Merge caller-supplied cookie options on top of the resolved defaults.
  * Caller-supplied values always win — `httpOnly: false` passed by a bundle
@@ -166,7 +289,15 @@ function Session(expressSession) {
         var defaults = resolveSettingsDefaults();
         options.cookie = mergeCookie(options.cookie, defaults);
         assertInvariant(options.cookie);
-        return expressSession(options);
+        // #COMPLY4 — resolve (and strip) the absolute-timeout cap before
+        // express-session sees the options; no cap means the raw middleware
+        // is returned untouched.
+        var absoluteMs = resolveAbsoluteTimeout(options, defaults);
+        var mw = expressSession(options);
+        if (!absoluteMs) {
+            return mw;
+        }
+        return makeAbsoluteTimeoutMiddleware(mw, absoluteMs);
     }
 
     var wrapped = function (options) { return ginaSessionDispatch(options); };
@@ -195,9 +326,11 @@ function Session(expressSession) {
 
 // Exposed for unit testing. Do not rely on these in application code — they
 // may change without notice.
-Session._resolveSettingsDefaults = resolveSettingsDefaults;
-Session._mergeCookie             = mergeCookie;
-Session._assertInvariant         = assertInvariant;
-Session._ALLOWED_SAMESITE        = ALLOWED_SAMESITE;
+Session._resolveSettingsDefaults        = resolveSettingsDefaults;
+Session._mergeCookie                    = mergeCookie;
+Session._assertInvariant                = assertInvariant;
+Session._ALLOWED_SAMESITE               = ALLOWED_SAMESITE;
+Session._resolveAbsoluteTimeout         = resolveAbsoluteTimeout;
+Session._makeAbsoluteTimeoutMiddleware  = makeAbsoluteTimeoutMiddleware;
 
 module.exports = Session;

package/framework/{v0.5.26 → v0.6.0}/core/router.js

@@ -389,6 +389,23 @@ function Router(env, scope) {
             ||
             typeof(request.login) == 'undefined'
         ) {
+            /**
+             * Login shim — authenticates the request AND, on the gina-native
+             * branch, rotates the session id before binding the user
+             * (session-fixation defense, #COMPLY4).
+             *
+             * Passport bundles never see this shim in normal operation
+             * (passport.initialize() installs its own req.login first); the
+             * Passport-flavored branch serves the HTTP2 case where
+             * `request._passport` exists without the request extensions.
+             *
+             * @param {object}   user      - authenticated principal; bound at
+             *                               `request.session.user` (what the authorization gate reads)
+             * @param {object}   [options] - `{session: false}` binds `request.user` only
+             *                               (transient — no session work, no rotation)
+             * @param {function} done      - REQUIRED callback `done(err)` on the session paths;
+             *                               fires after rotation + bind + persist complete
+             */
             request.login =
             request.logIn = function(user, options, done) {
                 if (typeof options == 'function') {
@@ -412,7 +429,52 @@ function Router(env, scope) {
 
 
                 if (!this._passport) {
-                    throw new Error('passport.initialize() middleware not in use');
+                    // #COMPLY4 — gina-native branch. This path previously ended
+                    // in a hard passport-required throw, so the framework's own
+                    // session pattern (authz reads `req.session.user`) had no
+                    // working login here. Now: rotate the session id BEFORE
+                    // binding the user (session-fixation defense), bind at
+                    // `session.user`, stamp the absolute-timeout anchor,
+                    // persist, then report. Same degrade-gracefully shape as
+                    // the #B164 logout shim below — typeof-gated, the session
+                    // provider's capabilities decide.
+                    if (typeof done != 'function') {
+                        throw new Error('req#login requires a callback function');
+                    }
+                    var req = this;
+                    if ( !req.session || typeof(req.session) != 'object' ) {
+                        req[property] = null;
+                        return done(new Error('req#login requires a session — register the Session plugin (or express-session) before routing'));
+                    }
+                    if ( typeof(req.session.regenerate) == 'function' ) {
+                        req.session.regenerate(function onLoginSessionRegenerated(err) {
+                            if (err) {
+                                req[property] = null;
+                                return done(err);
+                            }
+                            req.session.user = user;
+                            // absolute-timeout anchor — the clock starts at login
+                            req.session._ginaCreatedAt = Date.now();
+                            if ( typeof(req.session.save) == 'function' ) {
+                                return req.session.save(function onLoginSessionSaved(saveErr) {
+                                    done(saveErr || null);
+                                });
+                            }
+                            done(null);
+                        });
+                        return;
+                    }
+                    // no regenerate() on this session provider — bind without
+                    // rotation, and say so: the fixation defense is unavailable
+                    console.warn('[ ROUTER ] login(): session provider exposes no regenerate() — user bound WITHOUT session-id rotation');
+                    req.session.user = user;
+                    req.session._ginaCreatedAt = Date.now();
+                    if ( typeof(req.session.save) == 'function' ) {
+                        return req.session.save(function onLoginSessionSavedNoRotation(saveErr) {
+                            done(saveErr || null);
+                        });
+                    }
+                    return done(null);
                 }
                 if (typeof done != 'function') {
                     throw new Error('req#login requires a callback function');
@@ -436,8 +498,22 @@ function Router(env, scope) {
             typeof(request.session) != 'undefined'
             && typeof(request.logout) == 'undefined'
         ) {
+            /**
+             * Logout shim — de-authenticates the request AND destroys the
+             * persisted session record.
+             *
+             * #B164 — nulling `session.user` alone left the store record, the
+             * session id and every other session key alive until TTL. The
+             * gina-native branch now also calls the session's own destroy()
+             * when it exposes one (express-session), degrading gracefully when
+             * it does not. Clearing the session COOKIE stays the consumer's
+             * job — the cookie name is not discoverable from the request.
+             *
+             * @param {function} [done] - Optional callback `done(err)` invoked once
+             *                            record destruction (or the fallback) completes.
+             */
             request.logout =
-            request.logOut = function() {
+            request.logOut = function(done) {
                 var property = 'user';
 
                 // by default
@@ -445,25 +521,39 @@ function Router(env, scope) {
                 if (sess._passport && sess._passport.instance) {
                     property = sess._passport.instance._userProperty || 'user';
                 }
+                var isSessionScope = false;
                 if ( !sess._passport
                     && typeof(sess.session) != 'undefined'
                 ) {
                     sess = sess.session;
+                    isSessionScope = true;
                 }
 
                 sess[property] = null;
                 if (sess._passport) {
                     sess._passport.instance._sm.logOut(sess);
+                    if ( typeof(done) == 'function' ) {
+                        done(null);
+                    }
+                    return;
+                }
+                // #B164 — destroy the record, not just the `user` key. Gated on the
+                // session scope so a call after destruction (no `request.session`
+                // left) can never reach `request.destroy()` — the stream method.
+                if ( isSessionScope && typeof(sess.destroy) == 'function' ) {
+                    sess.destroy(function onLogoutSessionDestroyed(err) {
+                        if (err) {
+                            console.warn('[ ROUTER ] logout(): session.destroy() failed: ' + (err.stack || err.message || err));
+                        }
+                        if ( typeof(done) == 'function' ) {
+                            done(err || null);
+                        }
+                    });
+                    return;
+                }
+                if ( typeof(done) == 'function' ) {
+                    done(null);
                 }
-
-
-                // if (this._passport && this._passport.instance) {
-                //     property = this._passport.instance._userProperty || 'user';
-                // }
-                // this[property] = null;
-                // if (this._passport) {
-                //     this._passport.instance._sm.logOut(this);
-                // }
             };
         }
 

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

@@ -1341,6 +1341,42 @@ function Server(options) {
             if ( _auditSettings.store && _auditSettings.file ) {
                 throw new Error('[ SERVER ] `settings.json > audit`: `store` and `file` are mutually exclusive — pick one backend.');
             }
+            // ── #COMPLY2 slice 3 — tamper-evidence chain: shape lint (unconditional,
+            // like the rest of the audit lint family: a malformed block with the
+            // chain OFF is still an author error better surfaced now).
+            if ( typeof(_auditSettings.chain) != 'undefined' ) {
+                if ( typeof(_auditSettings.chain) != 'object' || _auditSettings.chain === null || Array.isArray(_auditSettings.chain) ) {
+                    throw new Error('[ SERVER ] `settings.json > audit.chain` must be an object.');
+                }
+                if ( typeof(_auditSettings.chain.enabled) != 'undefined' && typeof(_auditSettings.chain.enabled) != 'boolean' ) {
+                    throw new Error('[ SERVER ] `settings.json > audit.chain.enabled` must be a boolean — got '+ JSON.stringify(_auditSettings.chain.enabled) +'. A truthy string would leave tamper-evidence silently OFF, so the boot refuses instead.');
+                }
+                if ( typeof(_auditSettings.chain.secret) != 'undefined' && ( typeof(_auditSettings.chain.secret) != 'string' || _auditSettings.chain.secret === '' ) ) {
+                    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.');
+                }
+            }
+            var _auditChainEnabled = !!( _auditSettings.chain && _auditSettings.chain.enabled === true );
+            if ( _auditChainEnabled && !_auditEnabled ) {
+                console.warn('[ SERVER ] `audit.chain.enabled` is true but `audit.enabled` is false — the audit trail (and with it the chain) is OFF for [ '+ self.appName +' ].');
+            }
+            // Merged mode (shared port ⇒ one process) starts ONE trail — the
+            // starting bundle's. A sibling that declares `audit.enabled: true`
+            // is silently ignored otherwise (its block parses into envConf and
+            // nothing ever reads it — runtime-measured 2026-07-26), which is
+            // the quietly-OFF class this lint family exists to prevent: say so.
+            if ( self.isStandalone && Array.isArray(self.bundles) && self.bundles.length > 1 ) {
+                for (let _mb = 0; _mb < self.bundles.length; ++_mb) {
+                    if (self.bundles[_mb] === self.appName) continue;
+                    var _mbConf  = options.conf[self.bundles[_mb]] && options.conf[self.bundles[_mb]][self.env];
+                    var _mbAudit = ( _mbConf && _mbConf.content && _mbConf.content.settings && _mbConf.content.settings.audit ) ? _mbConf.content.settings.audit : null;
+                    if ( _mbAudit && _mbAudit.enabled === true ) {
+                        console.warn('[ SERVER ] [ audit ] bundle `'+ self.bundles[_mb] +'` declares `audit.enabled: true`, but in merged mode (shared port) only the starting bundle\'s audit settings apply — its audit configuration is IGNORED. The process-wide trail is governed by [ '+ self.appName +' ].');
+                    }
+                }
+            }
             if ( _auditEnabled ) {
                 var _auditStartOpts = {
                     bundle      : self.appName,
@@ -1379,13 +1415,67 @@ function Server(options) {
                     _auditStartOpts.file = _(_auditFile, true);
                     _auditDestLabel = _auditStartOpts.file;
                 }
+                if ( _auditChainEnabled ) {
+                    if ( _auditSettings.store ) {
+                        // The store seam carries NO ordering obligation — a
+                        // connector backend may persist out of emit order, and
+                        // a chain over reordered records forks silently.
+                        throw new Error('[ SERVER ] `audit.chain` requires the file backend — a connector `store` cannot guarantee the ordered append a hash chain needs. Remove `audit.store` or disable the chain.');
+                    }
+                    // Key resolution mirrors the CSRF secret chain, with the
+                    // GINA_* read through the framework env reader (the
+                    // GINA_MCP_AUTH_TOKEN precedent — the CLI sweeps GINA_*
+                    // out of process.env, so a direct read is empty there).
+                    var _auditChainSecret = ( typeof(_auditSettings.chain.secret) == 'string' && _auditSettings.chain.secret ) ? _auditSettings.chain.secret : null;
+                    if ( !_auditChainSecret ) {
+                        _auditChainSecret = ( typeof(getEnvVar) == 'function' && getEnvVar('GINA_AUDIT_SECRET') ) || process.env.GINA_AUDIT_SECRET || null;
+                    }
+                    if ( !_auditChainSecret || typeof(_auditChainSecret) != 'string' ) {
+                        throw new Error('[ SERVER ] `audit.chain.enabled` is true but no signing key is configured — set `settings.json > audit.chain.secret` (e.g. "${secret:MY_AUDIT_KEY}", a non-GINA variable name) or the GINA_AUDIT_SECRET environment variable. Tamper-evidence without a key would be silently OFF, so the boot refuses instead.');
+                    }
+                    if ( _auditChainSecret.length < 32 ) {
+                        console.warn('[ SERVER ] `audit.chain` signing key is shorter than 32 characters — a longer random key (>= 32 bytes) is recommended.');
+                    }
+                    _auditStartOpts.chain = { secret: _auditChainSecret };
+                }
+                // Cross-PROCESS shared-file refusal: two bundles resolving the
+                // SAME audit file run as separate writers in per-process mode,
+                // and two writers fork a linear hash chain. Boot-detectable in
+                // both modes — options.conf carries every bundle's parsed
+                // settings (runtime-measured 2026-07-26) — so the boot refuses
+                // when EITHER party chains. Without a chain the shared file
+                // stays legal (interleaved JSONL, pre-existing behaviour).
+                // Replicas and cross-project collisions are NOT detectable
+                // from config; the docs state that boundary.
+                if ( _auditStartOpts.file ) {
+                    for (var _ab in options.conf) {
+                        if (_ab === self.appName) continue;
+                        var _sibConf  = options.conf[_ab] && options.conf[_ab][self.env];
+                        var _sibAudit = ( _sibConf && _sibConf.content && _sibConf.content.settings && _sibConf.content.settings.audit ) ? _sibConf.content.settings.audit : null;
+                        if ( !_sibAudit || _sibAudit.enabled !== true || _sibAudit.store ) continue;
+                        var _sibChain = !!( _sibAudit.chain && _sibAudit.chain.enabled === true );
+                        if ( !_auditChainEnabled && !_sibChain ) continue;
+                        // replay the sibling's file derivation
+                        var _sibFile = ( typeof(_sibAudit.file) == 'string' && _sibAudit.file ) ? _sibAudit.file : null;
+                        if ( !_sibFile || !/^\//.test(_sibFile) ) {
+                            var _sibProjectPath = _sibConf.projectPath;
+                            if ( typeof(_sibProjectPath) != 'string' || _sibProjectPath === '' || /\$\{/.test(_sibProjectPath) ) continue; // unresolvable — its own boot lints it
+                            _sibFile = _sibFile
+                                ? _sibProjectPath + '/' + _sibFile
+                                : _sibProjectPath + '/logs/audit-'+ _ab +'-'+ self.env +'.jsonl';
+                        }
+                        if ( _( _sibFile, true) === _auditStartOpts.file ) {
+                            throw new Error('[ SERVER ] `audit.chain`: bundle `'+ _ab +'` resolves the SAME audit file ('+ _auditStartOpts.file +') and '+ ( _auditChainEnabled ? 'this bundle chains its trail' : 'that bundle chains its trail' ) +' — two writers fork a linear hash chain, so the boot refuses. Give each bundle its own `audit.file` (the default per-bundle path never collides), or disable the chain on both.');
+                        }
+                    }
+                }
                 // start() mkdirs + opens the O_APPEND fd — an unwritable destination
                 // throws HERE, i.e. refuses the boot rather than dropping records later.
                 lib.audit.start(_auditStartOpts);
                 // console.info, NOT console.debug — the shipped default log_level
                 // ("info") filters debug, which would silently defeat the
                 // "path logged at boot" contract.
-                console.info('[ BUNDLE ][ server ][ init ] Audit trail enabled for [ '+ self.appName +' ] → '+ _auditDestLabel);
+                console.info('[ BUNDLE ][ server ][ init ] Audit trail enabled for [ '+ self.appName +' ] → '+ _auditDestLabel + ( _auditChainEnabled ? ' (tamper-evident chain: ON)' : '' ));
             }
 
             // ── #B144 — upload write-error probe (`simulateWriteError`) boot warn ──

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

@@ -152,6 +152,9 @@
   //   httpOnly: true | false                 (default true)
   //   secure:   true | false | "auto"        (default "auto")
   // Invariant: sameSite="none" requires secure=true (browser-parity).
+  // #COMPLY4 — optional absolute session cap in ms since login (opt-in, none by default);
+  // bundle code session({ absoluteTimeout }) wins, false there disables:
+  //   "absoluteTimeout": 28800000,
   "session": {
     "cookie": {
       "sameSite": "lax",